@rizom/ops 0.2.0-alpha.0 → 0.2.0-alpha.10

package/dist/observed-status.d.ts

@@ -0,0 +1,12 @@
+import type { FetchLike } from "@brains/utils/origin-ca";
+import type { ObservedUserStatus, ResolvedUserIdentity } from "./load-registry";
+export interface LookupResult {
+    address: string;
+    family: number;
+}
+export type LookupHost = (hostname: string) => Promise<LookupResult>;
+export interface CreateObservedStatusResolverOptions {
+    fetchImpl?: FetchLike;
+    lookupHost?: LookupHost;
+}
+export declare function createObservedStatusResolver(options?: CreateObservedStatusResolverOptions): (user: ResolvedUserIdentity) => Promise<ObservedUserStatus>;

package/dist/origin-ca.d.ts

@@ -0,0 +1 @@
+export { createOriginCertificateRequest, generateOriginKeyPair, issueCloudflareOriginCertificate, setCloudflareZoneSslStrict, type CloudflareOriginCaResult, type FetchLike, type OriginCertificateRequest, type OriginKeyPair, } from "@brains/utils/origin-ca";

package/dist/parse-args.d.ts

@@ -4,6 +4,8 @@ export interface ParsedArgs {
     flags: {
         help?: boolean | undefined;
         version?: boolean | undefined;
+        dryRun?: boolean | undefined;
+        pushTo?: string | undefined;
     };
 }
 export declare function parseArgs(argv: string[]): ParsedArgs;

package/dist/push-secrets.d.ts

@@ -0,0 +1,9 @@
+import { normalizePushTarget, type PushTarget } from "./push-target";
+import { type RunCommand } from "./run-subprocess";
+export type SecretPair = readonly [name: string, value: string];
+export interface PushSecretsOptions {
+    runCommand?: RunCommand | undefined;
+    logger?: ((message: string) => void) | undefined;
+}
+export declare function pushSecretsToBackend(target: PushTarget, secrets: readonly SecretPair[], options?: PushSecretsOptions): Promise<void>;
+export { normalizePushTarget };

package/dist/push-target.d.ts

@@ -0,0 +1,2 @@
+export type PushTarget = "gh";
+export declare function normalizePushTarget(value?: string): PushTarget | undefined;

package/dist/run-command.d.ts

@@ -1,5 +1,9 @@
+import type { FetchLike } from "@brains/utils/origin-ca";
 import type { LoadPilotRegistryOptions } from "./load-registry";
+import { type LookupHost } from "./observed-status";
 import type { ParsedArgs } from "./parse-args";
+import { type RunCommand as OpsRunCommand } from "./run-subprocess";
+import { type SshKeygen } from "./ssh-key-bootstrap";
 import type { UserRunner } from "./user-runner";
 export interface CommandResult {
     success: boolean;
@@ -7,5 +11,12 @@ export interface CommandResult {
 }
 export interface CommandDependencies extends LoadPilotRegistryOptions {
     runner?: UserRunner;
+    env?: NodeJS.ProcessEnv | undefined;
+    logger?: ((message: string) => void) | undefined;
+    fetchImpl?: FetchLike | undefined;
+    lookupHost?: LookupHost | undefined;
+    secretRunCommand?: OpsRunCommand | undefined;
+    bootstrapRunCommand?: OpsRunCommand | undefined;
+    sshKeygen?: SshKeygen | undefined;
 }
 export declare function runCommand(parsed: ParsedArgs, dependencies?: CommandDependencies): Promise<CommandResult>;

package/dist/run-subprocess.d.ts

@@ -0,0 +1,5 @@
+export type RunCommand = (command: string, args: string[], options?: {
+    stdin?: string;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<void>;
+export declare const runSubprocess: RunCommand;

package/dist/schema.d.ts

@@ -19,7 +19,7 @@ export declare const pilotSchema: z.ZodObject<{
     githubOrg: string;
     contentRepoPrefix: string;
     domainSuffix: string;
-    preset: "core" | "default" | "pro";
+    preset: "default" | "core" | "pro";
     aiApiKey: string;
 }, {
     schemaVersion: 1;
@@ -28,7 +28,7 @@ export declare const pilotSchema: z.ZodObject<{
     githubOrg: string;
     contentRepoPrefix: string;
     domainSuffix: string;
-    preset: "core" | "default" | "pro";
+    preset: "default" | "core" | "pro";
     aiApiKey: string;
 }>;
 export declare const userSchema: z.ZodObject<{
@@ -63,22 +63,22 @@ export declare const cohortSchema: z.ZodEffects<z.ZodObject<{
     members: string[];
     aiApiKeyOverride?: string | undefined;
     brainVersionOverride?: string | undefined;
-    presetOverride?: "core" | "default" | "pro" | undefined;
+    presetOverride?: "default" | "core" | "pro" | undefined;
 }, {
     members: string[];
     aiApiKeyOverride?: string | undefined;
     brainVersionOverride?: string | undefined;
-    presetOverride?: "core" | "default" | "pro" | undefined;
+    presetOverride?: "default" | "core" | "pro" | undefined;
 }>, {
     members: string[];
     aiApiKeyOverride?: string | undefined;
     brainVersionOverride?: string | undefined;
-    presetOverride?: "core" | "default" | "pro" | undefined;
+    presetOverride?: "default" | "core" | "pro" | undefined;
 }, {
     members: string[];
     aiApiKeyOverride?: string | undefined;
     brainVersionOverride?: string | undefined;
-    presetOverride?: "core" | "default" | "pro" | undefined;
+    presetOverride?: "default" | "core" | "pro" | undefined;
 }>;
 export type PilotConfig = z.infer<typeof pilotSchema>;
 export type UserConfig = z.infer<typeof userSchema>;

package/dist/secrets-push.d.ts

@@ -0,0 +1,13 @@
+import { type RunCommand } from "./run-subprocess";
+export interface SecretsPushOptions {
+    env?: NodeJS.ProcessEnv | undefined;
+    logger?: ((message: string) => void) | undefined;
+    dryRun?: boolean | undefined;
+    runCommand?: RunCommand | undefined;
+}
+export interface SecretsPushResult {
+    pushedKeys: string[];
+    skippedKeys: string[];
+    dryRun?: boolean | undefined;
+}
+export declare function pushPilotSecrets(rootDir: string, handle: string, options?: SecretsPushOptions): Promise<SecretsPushResult>;

package/dist/ssh-key-bootstrap.d.ts

@@ -0,0 +1,26 @@
+import { type FetchLike } from "@brains/utils/origin-ca";
+import { type RunCommand } from "./run-subprocess";
+export interface SshKeyBootstrapOptions {
+    env?: NodeJS.ProcessEnv | undefined;
+    fetchImpl?: FetchLike | undefined;
+    logger?: (message: string) => void;
+    pushTo?: string | undefined;
+    runCommand?: RunCommand | undefined;
+    sshKeygen?: SshKeygen | undefined;
+}
+export interface SshKeyBootstrapResult {
+    createdHetznerKey: boolean;
+    createdLocalKey: boolean;
+    privateKeyPath: string;
+    publicKeyPath: string;
+    sshKeyName: string;
+}
+export interface SshKeygen {
+    createEd25519KeyPair: (privateKeyPath: string, comment: string) => void;
+    derivePublicKey: (privateKeyPath: string) => string;
+}
+export declare function runPilotSshKeyBootstrap(rootDir: string, options?: SshKeyBootstrapOptions): Promise<{
+    success: boolean;
+    message?: string;
+}>;
+export declare function bootstrapPilotSshKey(rootDir: string, options?: SshKeyBootstrapOptions): Promise<SshKeyBootstrapResult>;

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.0-alpha.0",
+  "version": "0.2.0-alpha.10",
   "type": "module",
   "exports": {
     ".": {
@@ -12,7 +12,7 @@
       "import": "./dist/index.js"
     },
     "./deploy": {
-      "bun": "./src/entries/deploy.ts",
+      "bun": "./dist/deploy.js",
       "types": "./dist/deploy.d.ts",
       "import": "./dist/deploy.js"
     }

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

@@ -54,6 +54,7 @@ jobs:
         with:
           context: .
           file: deploy/Dockerfile
+          target: fleet
           push: true
           build-args: |
             BRAIN_VERSION=${{ env.BRAIN_VERSION }}

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

@@ -28,6 +28,7 @@ jobs:
       - uses: actions/checkout@v5
         with:
           ref: ${{ github.sha }}
+          fetch-depth: 0
 
       - uses: oven-sh/setup-bun@v2
 
@@ -167,7 +168,9 @@ jobs:
           CF_ZONE_ID: ${{ secrets.CF_ZONE_ID }}
           BRAIN_DOMAIN: ${{ steps.user_config.outputs.brain_domain }}
           SERVER_IP: ${{ steps.provision.outputs.server_ip }}
-        run: bun deploy/scripts/update-dns.ts
+        run: |
+          bun deploy/scripts/update-dns.ts
+          BRAIN_DOMAIN="preview.$BRAIN_DOMAIN" bun deploy/scripts/update-dns.ts
 
       - name: Validate SSH key
         run: ssh-keygen -y -f ~/.ssh/id_ed25519 >/dev/null
@@ -191,6 +194,10 @@ jobs:
         env:
           SERVER_IP: ${{ steps.provision.outputs.server_ip }}
           VERSION: brain-${{ steps.user_config.outputs.brain_version }}
+          IMAGE_REPOSITORY: ${{ steps.user_config.outputs.image_repository }}
+          REGISTRY_USERNAME: ${{ steps.user_config.outputs.registry_username }}
+          BRAIN_DOMAIN: ${{ steps.user_config.outputs.brain_domain }}
+          BRAIN_YAML_PATH: ${{ steps.user_config.outputs.brain_yaml_path }}
         run: kamal setup --skip-push -c deploy/kamal/deploy.yml
 
       - name: Verify origin TLS
@@ -258,4 +265,4 @@ jobs:
           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
+          git push origin HEAD:${{ github.ref_name }}

package/templates/rover-pilot/README.md

@@ -36,7 +36,10 @@ When a push changes only deploy contract files, CI prints `No affected user conf
 ## Commands
 
 - `brains-ops init <repo>`
-- `brains-ops render <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 ssh-key:bootstrap <repo>`
+- `brains-ops cert:bootstrap <repo> <handle>`
+- `brains-ops secrets:push <repo> <handle>`
 - `brains-ops reconcile-cohort <repo> <cohort>`
 - `brains-ops reconcile-all <repo>`

package/templates/rover-pilot/deploy/Caddyfile

@@ -0,0 +1,67 @@
+# Internal Caddy — path-based routing to brain services.
+# kamal-proxy terminates TLS externally; this runs inside the container.
+:80 {
+	@preview host preview.*
+	handle @preview {
+		reverse_proxy localhost:4321
+
+		header {
+			X-Frame-Options "SAMEORIGIN"
+			X-Content-Type-Options "nosniff"
+			Referrer-Policy "strict-origin-when-cross-origin"
+		}
+	}
+
+	# Health endpoint
+	handle /health {
+		reverse_proxy localhost:3333
+	}
+
+	# MCP endpoint
+	handle /mcp* {
+		reverse_proxy localhost:3333
+
+		header {
+			X-Content-Type-Options "nosniff"
+			Access-Control-Allow-Origin "*"
+			Access-Control-Allow-Methods "GET, POST, DELETE, OPTIONS"
+			Access-Control-Allow-Headers "Content-Type, Authorization, MCP-Session-Id"
+		}
+	}
+
+	# A2A endpoints
+	handle /.well-known/agent-card.json {
+		reverse_proxy localhost:3334
+	}
+
+	handle /a2a {
+		reverse_proxy localhost:3334
+
+		header {
+			X-Content-Type-Options "nosniff"
+			Access-Control-Allow-Origin "*"
+			Access-Control-Allow-Methods "GET, POST, OPTIONS"
+			Access-Control-Allow-Headers "Content-Type, Authorization"
+		}
+	}
+
+	# Plugin API routes
+	handle /api/* {
+		reverse_proxy localhost:3335
+	}
+
+	# Production site: prefer the webserver when present; otherwise fall back
+	# to the A2A interface so core-only deployments never return a bare 502.
+	handle {
+		reverse_proxy localhost:8080 localhost:3334 {
+			lb_policy first
+			lb_retries 1
+		}
+
+		header {
+			X-Frame-Options "SAMEORIGIN"
+			X-Content-Type-Options "nosniff"
+			Referrer-Policy "strict-origin-when-cross-origin"
+		}
+	}
+}

package/templates/rover-pilot/deploy/Dockerfile

@@ -1,15 +1,38 @@
 ARG BUN_VERSION=1.3.10
-FROM oven/bun:${BUN_VERSION}-slim
+FROM oven/bun:${BUN_VERSION}-slim AS runtime
 
-ARG BRAIN_VERSION
 WORKDIR /app
 
-RUN test -n "$BRAIN_VERSION" \
- && printf '{"name":"rover-pilot-runtime","private":true}\n' > package.json \
- && bun add @rizom/brain@$BRAIN_VERSION
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl ca-certificates git gnupg debian-keyring debian-archive-keyring apt-transport-https \
+    && curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg \
+    && curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list \
+    && apt-get update && apt-get install -y --no-install-recommends caddy libcap2-bin \
+    && setcap cap_net_bind_service=+ep $(which caddy) \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY deploy/Caddyfile /etc/caddy/Caddyfile
+
+RUN mkdir -p /srv/fallback && \
+    printf '<!doctype html><html><head><meta charset="utf-8"><title>brain</title></head><body></body></html>\n' \
+    > /srv/fallback/index.html
 
 ENV XDG_DATA_HOME=/data
 ENV XDG_CONFIG_HOME=/config
-RUN mkdir -p /app/brain-data /data /config && chmod -R 777 /app/brain-data /data /config
+RUN mkdir -p /app/data /app/cache /app/brain-data && \
+    chmod -R 777 /app/data /app/cache /app/brain-data
 
-CMD ["sh", "-c", "exec ./node_modules/.bin/brain start"]
+CMD ["sh", "-c", "caddy start --config /etc/caddy/Caddyfile && exec ./node_modules/.bin/brain start"]
+
+# --- standalone: bake full project into image (brain-cli deploy) ---
+FROM runtime AS standalone
+COPY package.json ./package.json
+RUN bun install --production --ignore-scripts
+COPY . .
+
+# --- fleet: install published brain at pinned version (ops deploy) ---
+FROM runtime AS fleet
+ARG BRAIN_VERSION
+RUN test -n "$BRAIN_VERSION" \
+ && printf '{"name":"rover-pilot-runtime","private":true}\n' > package.json \
+ && bun add @rizom/brain@$BRAIN_VERSION

package/templates/rover-pilot/deploy/kamal/deploy.yml

@@ -2,7 +2,7 @@ service: rover
 image: <%= ENV['IMAGE_REPOSITORY'] %>
 
 servers:
-  mcp:
+  web:
     hosts:
       - <%= ENV['SERVER_IP'] %>
 
@@ -12,7 +12,8 @@ proxy:
     private_key_pem: PRIVATE_KEY_PEM
   hosts:
     - <%= ENV['BRAIN_DOMAIN'] %>
-  app_port: 3333
+    - preview.<%= ENV['BRAIN_DOMAIN'] %>
+  app_port: 80
   healthcheck:
     path: /health
 

package/templates/rover-pilot/deploy/scripts/provision-server.ts

@@ -0,0 +1,109 @@
+import {
+  readJsonResponse,
+  requireEnv,
+  writeGitHubOutput,
+  writeGitHubEnv,
+} from "./helpers";
+
+const token = requireEnv("HCLOUD_TOKEN");
+const instanceName = requireEnv("INSTANCE_NAME");
+const sshKeyName = requireEnv("HCLOUD_SSH_KEY_NAME");
+const serverType = requireEnv("HCLOUD_SERVER_TYPE");
+const location = requireEnv("HCLOUD_LOCATION");
+
+const headers: Record<string, string> = {
+  Authorization: `Bearer ${token}`,
+  "Content-Type": "application/json",
+};
+const baseUrl = "https://api.hetzner.cloud/v1";
+const labelSelector = `brain=${instanceName}`;
+const MAX_POLLS = 30;
+const POLL_INTERVAL_MS = 10_000;
+
+interface HetznerServer {
+  id: number;
+  status: string;
+  public_net?: { ipv4?: { ip?: string } };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function listServers(): Promise<HetznerServer[]> {
+  const url = `${baseUrl}/servers?label_selector=${encodeURIComponent(labelSelector)}`;
+  const response = await fetch(url, { headers });
+  const payload = (await readJsonResponse(
+    response,
+    "Hetzner server lookup",
+  )) as {
+    servers?: HetznerServer[];
+  };
+  if (!response.ok || !payload.servers) {
+    throw new Error(`Hetzner server lookup failed: ${JSON.stringify(payload)}`);
+  }
+  return payload.servers;
+}
+
+async function createServer(): Promise<HetznerServer> {
+  const response = await fetch(`${baseUrl}/servers`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      name: instanceName,
+      server_type: serverType,
+      image: "ubuntu-22.04",
+      location,
+      ssh_keys: [sshKeyName],
+      labels: { brain: instanceName },
+    }),
+  });
+  const payload = (await readJsonResponse(
+    response,
+    "Hetzner server create",
+  )) as {
+    server?: HetznerServer;
+  };
+  if (!response.ok || !payload.server) {
+    throw new Error(`Hetzner server create failed: ${JSON.stringify(payload)}`);
+  }
+  return payload.server;
+}
+
+async function getServer(id: number): Promise<HetznerServer> {
+  const response = await fetch(`${baseUrl}/servers/${id}`, { headers });
+  const payload = (await readJsonResponse(response, "Hetzner server poll")) as {
+    server?: HetznerServer;
+  };
+  if (!response.ok || !payload.server) {
+    throw new Error(`Hetzner server poll failed: ${JSON.stringify(payload)}`);
+  }
+  return payload.server;
+}
+
+let server: HetznerServer | undefined = (await listServers())[0];
+server ??= await createServer();
+
+let polls = 0;
+while (server.status !== "running" || !server.public_net?.ipv4?.ip) {
+  if (++polls > MAX_POLLS) {
+    throw new Error(
+      `Server ${server.id} did not become ready after ${(MAX_POLLS * POLL_INTERVAL_MS) / 1000}s (status: ${server.status})`,
+    );
+  }
+  if (server.status === "error") {
+    throw new Error(`Server ${server.id} entered error state`);
+  }
+  console.log(
+    `Waiting for server ${server.id} (status: ${server.status}, poll ${polls}/${MAX_POLLS})...`,
+  );
+  await sleep(POLL_INTERVAL_MS);
+  server = await getServer(server.id);
+}
+
+const serverIp = server.public_net?.ipv4?.ip;
+if (!serverIp) {
+  throw new Error(`Server ${server.id} running but has no IPv4 address`);
+}
+writeGitHubOutput("server_ip", serverIp);
+writeGitHubEnv("SERVER_IP", serverIp);

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

@@ -0,0 +1,55 @@
+import { readJsonResponse, requireEnv } from "./helpers";
+
+const token = requireEnv("CF_API_TOKEN");
+const zoneId = requireEnv("CF_ZONE_ID");
+const domain = requireEnv("BRAIN_DOMAIN");
+const serverIp = requireEnv("SERVER_IP");
+
+const headers: Record<string, string> = {
+  Authorization: `Bearer ${token}`,
+  "Content-Type": "application/json",
+};
+const baseUrl = "https://api.cloudflare.com/client/v4";
+
+interface CloudflareResult {
+  success: boolean;
+  result?: Array<{ id: string }>;
+}
+
+async function upsertRecord(name: string): Promise<void> {
+  const lookupUrl = `${baseUrl}/zones/${zoneId}/dns_records?type=A&name=${encodeURIComponent(name)}`;
+  const lookup = await fetch(lookupUrl, { headers });
+  const payload = (await readJsonResponse(
+    lookup,
+    "Cloudflare DNS lookup",
+  )) as CloudflareResult;
+  if (!lookup.ok || !payload.success) {
+    throw new Error(`Cloudflare DNS lookup failed: ${JSON.stringify(payload)}`);
+  }
+
+  const existing = payload.result?.[0];
+  const url = existing
+    ? `${baseUrl}/zones/${zoneId}/dns_records/${existing.id}`
+    : `${baseUrl}/zones/${zoneId}/dns_records`;
+
+  const response = await fetch(url, {
+    method: existing ? "PUT" : "POST",
+    headers,
+    body: JSON.stringify({
+      type: "A",
+      name,
+      content: serverIp,
+      ttl: 1,
+      proxied: true,
+    }),
+  });
+  const result = (await readJsonResponse(
+    response,
+    "Cloudflare DNS upsert",
+  )) as CloudflareResult;
+  if (!response.ok || !result.success) {
+    throw new Error(`Cloudflare DNS upsert failed: ${JSON.stringify(result)}`);
+  }
+}
+
+await upsertRecord(domain);

package/templates/rover-pilot/deploy/scripts/validate-secrets.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import { parseEnvSchema } from "./helpers";
+
+const envSchemaPath = ".env.schema";
+const schema = parseEnvSchema(readFileSync(envSchemaPath, "utf8"));
+const requiredKeys = schema
+  .filter((entry) => entry.required)
+  .map((entry) => entry.key);
+
+const missing: string[] = [];
+for (const key of requiredKeys) {
+  if (!process.env[key]) {
+    missing.push(key);
+  }
+}
+
+if (missing.length > 0) {
+  throw new Error(`Missing required secrets: ${missing.join(", ")}`);
+}

package/templates/rover-pilot/deploy/scripts/write-kamal-secrets.ts

@@ -0,0 +1,18 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { parseEnvSchema } from "./helpers";
+
+const envSchemaPath = ".env.schema";
+const schema = parseEnvSchema(readFileSync(envSchemaPath, "utf8"));
+const sensitiveKeys = schema
+  .filter((entry) => entry.sensitive)
+  .map((entry) => entry.key);
+
+const lines: string[] = [];
+for (const name of sensitiveKeys) {
+  const value = process.env[name] ?? "";
+  const escaped = String(value).replace(/'/g, "'\\''");
+  lines.push(`${name}='${escaped}'`);
+}
+
+mkdirSync(".kamal", { recursive: true });
+writeFileSync(".kamal/secrets", lines.join("\n") + "\n");

package/templates/rover-pilot/deploy/scripts/write-ssh-key.ts

@@ -0,0 +1,17 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { requireEnv } from "./helpers";
+
+const privateKey = requireEnv("KAMAL_SSH_PRIVATE_KEY");
+
+let normalized = privateKey.replace(/\r\n/g, "\n").replace(/\\n/g, "\n");
+if (!normalized.endsWith("\n")) {
+  normalized += "\n";
+}
+
+const sshDir = join(process.env["HOME"] ?? "/root", ".ssh");
+mkdirSync(sshDir, { recursive: true });
+writeFileSync(join(sshDir, "id_ed25519"), normalized, {
+  encoding: "utf8",
+  mode: 0o600,
+});

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

@@ -5,6 +5,13 @@
 3. Add or edit `users/<handle>.yaml`.
 4. Add the user to a cohort in `cohorts/*.yaml`.
 5. Run `bunx brains-ops render <repo>`.
-6. Run `bunx brains-ops onboard <repo> <handle>`.
-7. 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.
-8. Hand the MCP connection details to the user.
+6. Run `bunx brains-ops ssh-key:bootstrap <repo> --push-to gh`.
+7. Run `bunx brains-ops cert:bootstrap <repo> <handle> --push-to gh`.
+8. Run `bunx brains-ops secrets:push <repo> <handle>`.
+9. Run `bunx brains-ops onboard <repo> <handle>`.
+10. Verify the deployed rover core contract:
+    - `https://<handle>.rizom.ai/health` returns `200`
+    - unauthenticated `POST https://<handle>.rizom.ai/mcp` returns `401`
+11. 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.
+12. Hand the MCP connection details to the user.
+13. Send `docs/user-onboarding.md` to the user as the pilot handoff guide.

package/templates/rover-pilot/docs/operator-playbook.md

@@ -33,6 +33,17 @@ When a push changes only deploy contract files and no generated `users/<handle>/
 
 They are scaffolded from `@rizom/ops`, then versioned in this repo like any other deploy contract.
 
+## Bootstrap flow
+
+For a new pilot user, the operator bootstrap order is:
+
+1. `bunx brains-ops ssh-key:bootstrap <repo> --push-to gh`
+2. `bunx brains-ops cert:bootstrap <repo> <handle> --push-to gh`
+3. `bunx brains-ops secrets:push <repo> <handle>`
+4. `bunx brains-ops onboard <repo> <handle>`
+
+`brains-ops cert:bootstrap` writes local cert artifacts under `.brains-ops/`, which stays repo-local and ignored by git.
+
 ## Upgrading operator behavior
 
 When `@rizom/ops` changes the scaffolded deploy contract:
@@ -42,6 +53,16 @@ When `@rizom/ops` changes the scaffolded deploy contract:
 3. review the resulting changes to `.env.schema`, `deploy/scripts/`, and workflows in git
 4. commit the updated deploy artifacts together
 
+## Rover-core verification notes
+
+Rover core is MCP-only. Do not expect the bare domain to serve a website.
+
+Use these checks after deploy:
+
+- `https://<handle>.rizom.ai/health` should return `200`
+- unauthenticated `POST https://<handle>.rizom.ai/mcp` should return `401 Unauthorized: Bearer token required`
+- a bare `GET /` may also return `401`; that is expected for rover core and does not indicate a bad deploy
+
 ## Recovery notes
 
 Document known failure modes, recovery steps, and operator notes here.