@rizom/ops 0.2.0-alpha.242 → 0.2.0-alpha.244

package/dist/legacy-pilot-migration.d.ts

@@ -0,0 +1,11 @@
+import { type CohortConfig, type PilotConfig } from "./schema";
+/** Offline-only conversion. Active desired-state loading never calls this. */
+export declare function migrateLegacyPilotConfig(input: unknown): PilotConfig;
+/** Offline-only cohort conversion. */
+export declare function migrateLegacyCohortConfig(input: unknown): CohortConfig;
+/** Offline-only YAML rewrite that retains comments while changing the schema. */
+export declare function migrateLegacyPilotYaml(input: string): string;
+/** Offline-only cohort rewrite that retains comments while changing selection. */
+export declare function migrateLegacyCohortYaml(input: string): string;
+export declare function renderPilotConfig(config: PilotConfig): string;
+export declare function renderCohortConfig(config: CohortConfig): string;

package/dist/load-registry.d.ts

@@ -1,4 +1,4 @@
-import { type PilotConfig, type PilotPreset } from "./schema";
+import { type PilotConfig, type CanonicalBundleId } from "./schema";
 export type ExternalStatus = "unknown" | "ready" | "failed";
 export type SnapshotStatus = "present" | "missing";
 export interface ObservedUserStatus {
@@ -11,7 +11,9 @@ export interface ResolvedCohort {
     id: string;
     members: string[];
     brainVersionOverride?: string;
-    presetOverride?: PilotPreset;
+    bundlesOverride?: CanonicalBundleId[];
+    addOverride?: string[];
+    removeOverride?: string[];
     aiApiKeyOverride?: string;
     gitSyncTokenOverride?: string;
 }
@@ -74,13 +76,13 @@ export interface ResolvedUserIdentity {
     handle: string;
     cohort: string;
     brainVersion: string;
-    model: "rover";
-    preset: PilotPreset;
+    bundles: CanonicalBundleId[];
+    add: string[];
+    remove: string[];
     domain: string;
     cloudflareZoneId?: string | undefined;
     contentRepo: string;
     profileKind?: string | undefined;
-    addOverride?: string[];
     siteOverride?: ResolvedSiteOverride;
     discordEnabled: boolean;
     discordAnchorUserId?: string;

package/dist/reconcile-dry-run.d.ts

@@ -0,0 +1,9 @@
+export interface ReconcileDryRunResult {
+    firstPassChangedFiles: string[];
+    secondPassChangedFiles: string[];
+}
+/**
+ * Reconcile an isolated copy twice with external content-repo access disabled.
+ * The source repository is never written.
+ */
+export declare function dryRunReconcileAll(rootDir: string): Promise<ReconcileDryRunResult>;

package/dist/schema.d.ts

@@ -1,26 +1,46 @@
 import { z } from "@brains/utils/zod";
-export declare const presetSchema: z.ZodEnum<{
-    core: "core";
-    default: "default";
-    pro: "pro";
-}>;
 export declare const exactVersionSchema: z.ZodString;
 export declare const handleSchema: z.ZodString;
 export declare const secretNameSchema: z.ZodString;
 export declare const agePublicKeySchema: z.ZodString;
-export declare const pilotSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    brainVersion: z.ZodString;
-    model: z.ZodLiteral<"rover">;
-    githubOrg: z.ZodString;
-    contentRepoPrefix: z.ZodString;
-    domainSuffix: z.ZodString;
-    preset: typeof presetSchema;
-    aiApiKey: z.ZodString;
-    gitSyncToken: z.ZodString;
-    contentRepoAdminToken: z.ZodString;
-    agePublicKey: z.ZodString;
+export declare const canonicalBundleIdSchema: z.ZodEnum<{
+    core: "core";
+    site: "site";
+    publishing: "publishing";
+    team: "team";
 }>;
+export type CanonicalBundleId = z.output<typeof canonicalBundleIdSchema>;
+export interface PilotConfig {
+    brainVersion: string;
+    bundles: CanonicalBundleId[];
+    add?: string[] | undefined;
+    remove?: string[] | undefined;
+    githubOrg: string;
+    contentRepoPrefix: string;
+    domainSuffix: string;
+    aiApiKey: string;
+    gitSyncToken: string;
+    contentRepoAdminToken: string;
+    agePublicKey: string;
+}
+export interface SiteOverrideConfig {
+    package: string;
+    version: string;
+    theme?: string | undefined;
+    themeVersion?: string | undefined;
+}
+export interface CohortConfig {
+    members: string[];
+    brainVersionOverride?: string | undefined;
+    bundlesOverride?: CanonicalBundleId[] | undefined;
+    addOverride?: string[] | undefined;
+    removeOverride?: string[] | undefined;
+    aiApiKeyOverride?: string | undefined;
+    gitSyncTokenOverride?: string | undefined;
+}
+/** Sole active desired-state contract for the canonical brain. */
+export declare const pilotSchema: z.ZodType<PilotConfig>;
+export declare const cohortSchema: z.ZodType<CohortConfig>;
 declare const anchorProfileSocialLinkSchema: z.ZodObject<{
     platform: z.ZodEnum<{
         github: "github";
@@ -70,12 +90,7 @@ declare const atprotoSchema: z.ZodObject<{
     lexiconAuthority: z.ZodOptional<z.ZodBoolean>;
     jetstream: z.ZodOptional<typeof atprotoJetstreamSchema>;
 }>;
-declare const siteOverrideSchema: z.ZodObject<{
-    package: z.ZodString;
-    version: z.ZodOptional<typeof exactVersionSchema>;
-    theme: z.ZodOptional<z.ZodString>;
-    themeVersion: z.ZodOptional<typeof exactVersionSchema>;
-}>;
+export declare const siteOverrideSchema: z.ZodType<SiteOverrideConfig>;
 declare const playbooksSchema: z.ZodObject<{
     onboarding: z.ZodOptional<z.ZodBoolean>;
 }>;
@@ -92,24 +107,15 @@ export declare const userSchema: z.ZodObject<{
     contentRepoOverride: z.ZodOptional<z.ZodString>;
     profileKind: z.ZodOptional<z.ZodString>;
     addOverride: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    removeOverride: z.ZodOptional<z.ZodArray<z.ZodString>>;
     siteOverride: z.ZodOptional<typeof siteOverrideSchema>;
     setup: z.ZodOptional<typeof setupDeliverySchema>;
     atproto: z.ZodOptional<typeof atprotoSchema>;
     playbooks: z.ZodOptional<typeof playbooksSchema>;
     anchorProfile: z.ZodOptional<typeof anchorProfileSchema>;
 }>;
-export declare const cohortSchema: z.ZodObject<{
-    members: z.ZodArray<z.ZodString>;
-    brainVersionOverride: z.ZodOptional<z.ZodString>;
-    presetOverride: z.ZodOptional<typeof presetSchema>;
-    aiApiKeyOverride: z.ZodOptional<z.ZodString>;
-    gitSyncTokenOverride: z.ZodOptional<z.ZodString>;
-}>;
-export type PilotConfig = z.output<typeof pilotSchema>;
 export type PilotConfigInput = z.input<typeof pilotSchema>;
 export type UserConfig = z.output<typeof userSchema>;
 export type UserConfigInput = z.input<typeof userSchema>;
-export type CohortConfig = z.output<typeof cohortSchema>;
 export type CohortConfigInput = z.input<typeof cohortSchema>;
-export type PilotPreset = z.output<typeof presetSchema>;
 export {};

package/dist/secrets-encrypt.d.ts

@@ -2,6 +2,8 @@ import { z } from "@brains/utils/zod";
 declare const encryptedUserSecretsSchema: z.ZodObject<{
     gitSyncToken: z.ZodOptional<z.ZodString>;
     discordBotToken: z.ZodOptional<z.ZodString>;
+    discordPublicKey: z.ZodOptional<z.ZodString>;
+    discordApplicationId: z.ZodOptional<z.ZodString>;
     aiApiKey: z.ZodOptional<z.ZodString>;
     atprotoAppPassword: z.ZodOptional<z.ZodString>;
     certificatePem: z.ZodOptional<z.ZodString>;

package/dist/stage-legacy-crossover.d.ts

@@ -0,0 +1,20 @@
+import { type SiteOverrideConfig } from "./schema";
+export interface StagedCrossover {
+    outputDir: string;
+    changedFiles: string[];
+}
+interface ReviewedSitePinManifest {
+    sites: Record<string, SiteOverrideConfig>;
+}
+export type ReviewedSitePins = ReviewedSitePinManifest["sites"];
+export interface StageLegacyCrossoverOptions {
+    sitePins?: ReviewedSitePins | undefined;
+}
+export declare function parseReviewedSitePins(input: string): ReviewedSitePins;
+export declare function loadReviewedSitePins(filePath: string): Promise<ReviewedSitePins>;
+/**
+ * Build a complete review copy without mutating the source repository.
+ * This is offline migration tooling; active desired-state loading is canonical-only.
+ */
+export declare function stageLegacyCrossover(sourceDir: string, outputDir: string, options?: StageLegacyCrossoverOptions): Promise<StagedCrossover>;
+export {};

package/dist/verify-user.d.ts

@@ -10,7 +10,7 @@ export interface FailedCheck {
 }
 export interface VerifyPilotUserResult {
     handle: string;
-    preset: ResolvedUser["preset"];
+    bundles: ResolvedUser["bundles"];
     domain: string;
     contentRepo: string;
     checks: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rizom/ops",
-  "version": "0.2.0-alpha.242",
+  "version": "0.2.0-alpha.244",
   "description": "Operator CLI for managing private brain fleet registry repos",
   "keywords": [
     "brains",
@@ -17,7 +17,8 @@
   },
   "bugs": "https://github.com/rizom-ai/brains/issues",
   "dependencies": {
-    "age-encryption": "^0.3.0"
+    "age-encryption": "^0.3.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@brains/deploy-support": "workspace:*",

package/templates/rover-pilot/.env.schema

@@ -25,6 +25,13 @@ CONTENT_REPO_ADMIN_TOKEN=
 # @sensitive
 DISCORD_BOT_TOKEN=
 
+# Stored with the per-user Discord credentials and injected at deploy time.
+# @sensitive
+DISCORD_PUBLIC_KEY=
+
+# @sensitive
+DISCORD_APPLICATION_ID=
+
 # AT Protocol publishing/discovery (optional, per-user)
 # Comes from the decrypted users/<handle>.secrets.yaml.age file when configured.
 # @sensitive

package/templates/rover-pilot/README.md

@@ -1,6 +1,6 @@
-# rover-pilot
+# private brain pilot
 
-Private desired-state repo for the rover pilot.
+Private desired-state repository for the hosted brain pilot. The generated repository/service name may remain `rover-pilot` for deployment identity compatibility.
 
 This is a single operator-owned repo. Pilot users do not get their own brain repos.
 Per-user deploy config lives under `users/<handle>/`, while content stays in per-user content repos.
@@ -31,7 +31,7 @@ The repo also checks in its deploy contract:
 `.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 default pilot image tag is `brain-${brainVersion}` end to end. A user with `siteOverride` gets an isolated `brain-${brainVersion}-sites-${packageHash}` image instead.
-When the effective brain version (`pilot.yaml.brainVersion`, or a cohort override) changes and you push, CI rebuilds the required default/site tags, refreshes generated user env files, and redeploys affected users. An omitted `siteOverride.version` follows that effective version; an explicit exact version remains pinned.
+When the effective brain version (`pilot.yaml.brainVersion`, or a cohort override) changes and you push, CI rebuilds the required default/site tags, refreshes generated user env files, and redeploys affected users. Every external site and theme package uses its own required exact version pin; ops never infers either version from the brain or from another package.
 When a push changes only deploy contract files, CI prints `No affected user configs; skipping deploy.` and stops before Kamal.
 
 ## Commands
@@ -46,3 +46,6 @@ When a push changes only deploy contract files, CI prints `No affected user conf
 - `brains-ops secrets:encrypt <repo> <handle>`
 - `brains-ops reconcile-cohort <repo> <cohort>`
 - `brains-ops reconcile-all <repo>`
+- `brains-ops reconcile-all <repo> --dry-run` (isolated, no external content-repository access)
+
+Use `docs/canonical-crossover-record.md` to record exact forward and rollback artifact pins before an approved crossover window.

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

@@ -25,6 +25,8 @@ writeSecretGitHubEnv(
   secrets["cmsContentRepoPat"] ?? secrets["gitSyncToken"],
 );
 writeSecretGitHubEnv("DISCORD_BOT_TOKEN", secrets["discordBotToken"]);
+writeSecretGitHubEnv("DISCORD_PUBLIC_KEY", secrets["discordPublicKey"]);
+writeSecretGitHubEnv("DISCORD_APPLICATION_ID", secrets["discordApplicationId"]);
 // Per-user AT Protocol publishing credential (optional; from the user's
 // encrypted secrets file). The scaffold wires this so a pilot can publish its
 // brain's agent card to its PDS; a deployment that doesn't publish simply

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

@@ -14,6 +14,17 @@ for (const key of requiredKeys) {
   }
 }
 
+const discordKeys = [
+  "DISCORD_BOT_TOKEN",
+  "DISCORD_PUBLIC_KEY",
+  "DISCORD_APPLICATION_ID",
+];
+if (discordKeys.some((key) => process.env[key])) {
+  for (const key of discordKeys) {
+    if (!process.env[key]) missing.push(key);
+  }
+}
+
 if (missing.length > 0) {
   throw new Error(`Missing required secrets: ${missing.join(", ")}`);
 }

package/templates/rover-pilot/docs/canonical-crossover-record.md

@@ -0,0 +1,103 @@
+# Canonical Crossover Approval Record
+
+> Draft evidence record only. Completing this file does not authorize a merge, publish, reconcile, or deployment.
+
+Do not include secret values, private keys, access tokens, or decrypted user configuration.
+
+## Authorization and freeze
+
+- Operator:
+- Approval reference:
+- Approved window:
+- Freeze start:
+- Build workflow disabled and idle:
+- Reconcile workflow disabled and idle:
+- Deploy workflow disabled and idle:
+
+## Reviewed inputs
+
+- `brains` crossover commit:
+- Private-pilot source commit used for staging:
+- Canonical review commit:
+- Secret-free review diff SHA-256:
+- Identity-review evidence SHA-256:
+- Reviewed hosted-site pin manifest SHA-256:
+- Source and review worktrees clean:
+
+## Hosted site and theme pins
+
+List every hosted site. External site and theme package versions must be exact and must
+match the staged user desired state; do not infer them from the brain or from each other.
+
+| Handle | Site package | Exact site version | Theme package | Exact theme version | Package/image evidence |
+| ------ | ------------ | ------------------ | ------------- | ------------------- | ---------------------- |
+|        |              |                    |               |                     |                        |
+
+## Forward artifact pins
+
+| Artifact               | Exact version | Registry integrity or digest | Verified installable |
+| ---------------------- | ------------- | ---------------------------- | -------------------- |
+| `@rizom/brain`         |               |                              |                      |
+| `@rizom/ops`           |               |                              |                      |
+| private-pilot lockfile | n/a           |                              |                      |
+
+Record every image. Tags alone are not immutable evidence.
+
+| Cohort/handle | Config commit | Image repository | Image tag | Image digest |
+| ------------- | ------------- | ---------------- | --------- | ------------ |
+|               |               |                  |           |              |
+
+## Rollback pair
+
+- Prior private-pilot commit:
+- Prior `@rizom/ops` version and registry integrity:
+
+| Cohort/handle | Prior config commit | Prior image repository | Prior image tag | Prior image digest |
+| ------------- | ------------------- | ---------------------- | --------------- | ------------------ |
+|               |                     |                        |                 |                    |
+
+## Identity review
+
+- Repository and image names unchanged or explicitly approved:
+- GitHub organization and content repository identities unchanged:
+- Server, domain, Cloudflare zone, and ATProto identities unchanged:
+- Secret selector names and encrypted secret artifacts unchanged:
+- Per-user runtime-version and site-package tag inputs reviewed:
+- No plaintext source secrets copied into the review artifact:
+- No removed model, preset, or old-format schema discriminator remains:
+- Every external hosted site and theme package has an exact reviewed pin:
+
+## Offline convergence
+
+Command:
+
+```sh
+bunx brains-ops reconcile-all <canonical-review-copy> --dry-run
+```
+
+- First-pass changed files:
+- Second-pass changed files (must be zero):
+- Review copy unchanged:
+- External content-repository access blocked:
+
+## Pre-window validation
+
+- Package tests, typecheck, lint, build, and packed-consumer startup:
+- Architecture and dependency boundaries:
+- Environment-schema and workspace checks:
+- Crossover migration and comment preservation:
+- Canary-first order and health checks reviewed:
+- Paired rollback reviewed:
+
+## Execution record
+
+Complete only inside the explicitly approved maintenance window.
+
+- Unified packages published and verified:
+- Canonical desired state committed while automation remained frozen:
+- Image digest set matched this record:
+- First reconcile reviewed:
+- Per-instance health, MCP authorization, identity, content, and site checks:
+- Second reconcile produced zero drift and no deploy work:
+- Freeze lifted:
+- One-week soak start:

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

@@ -23,18 +23,14 @@
 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 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 required default/site image tags, refreshes generated user env files, and redeploys affected users. Site overrides follow the user's effective brain version unless they declare an explicit exact `version` pin.
+13. Verify the deployed canonical contract:
+    - `https://<handle>.rizom.ai/health` returns `200`
+    - `https://<handle>.rizom.ai/chat` loads the web chat and accepts passkey sign-in
+    - 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
+    - when `site` is selected, the browser/CMS surfaces load and the initial app-managed site build completes
+14. For fleet upgrades, edit `pilot.yaml.brainVersion` and push once; CI rebuilds the required default/site image tags, refreshes generated user env files, and redeploys affected users. Every external site and theme package keeps its own required exact version pin and never follows the brain version implicitly.
 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`

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

@@ -30,14 +30,42 @@ When `pilot.yaml.brainVersion` changes and you push:
 3. deploy runs for handles whose generated config changed
 4. generated file commits happen once in a final aggregation step after the deploy matrix finishes
 
-An omitted `siteOverride.version` follows the user's effective brain version, so a
-cohort or pilot version bump advances its site and theme packages automatically.
-Set an exact `siteOverride.version` only when that user needs a deliberate pin.
+Every external site and theme package has its own exact version pin. A cohort or
+pilot brain-version bump never changes those package versions implicitly; update each
+pin deliberately from reviewed package and image evidence.
 
 When a push changes only deploy contract files and no generated `users/<handle>/.env` or `users/<handle>/brain.yaml` files, the deploy workflow exits through its explicit no-op path and prints `No affected user configs; skipping deploy.`
 
 They are scaffolded from `@rizom/ops`, then versioned in this repo like any other deploy contract.
 
+## Canonical contract crossover maintenance window
+
+Do not run this procedure without explicit operator approval. The canonical desired state, canonical `@rizom/ops`, and unified runtime image form one contract and must move or roll back together. Complete `docs/canonical-crossover-record.md` as the approval evidence without adding secret values.
+
+Before the window, record and review:
+
+- the prior pilot commit and exact `@rizom/ops` version;
+- every prior runtime image tag and immutable digest;
+- the reviewed canonical pilot commit;
+- the exact unified `@rizom/brain` and `@rizom/ops` versions;
+- every unified image tag and immutable digest;
+- canary-first rollout order, followed by the remaining cohorts;
+- expected `/health` version, unauthenticated MCP response, site marker, and content repository identity for each posture.
+
+Run `bunx brains-ops reconcile-all <canonical-review-copy> --dry-run` against the isolated review copy. The command blocks external content-repository access, leaves the review copy untouched, and must report second-pass zero drift.
+
+During the approved window:
+
+1. Freeze unrelated merges and releases. Wait for active Build, Reconcile, and Deploy runs to finish, then disable all three pilot workflows with `gh workflow disable build.yml`, `gh workflow disable reconcile.yml`, and `gh workflow disable deploy.yml`.
+2. Publish and verify the reviewed unified runtime and matching ops artifacts. Do not update pilot desired state until the exact versions are installable and the expected images can be built.
+3. Apply the reviewed canonical pilot revision while automation remains disabled. Confirm repository names, server/domain identity, content repositories, secret selectors, image names, and tag identity against the review diff.
+4. Enable only Build, run it for the canonical desired-state revision, and record every resulting image digest. Stop if the observed digest set differs from the cutover record.
+5. Enable only Reconcile, run it once, and review its generated config commit. No generated file may combine canonical config with a retired image version.
+6. Enable Deploy and deploy one handle at a time in the approved order. After each deploy, run `bunx brains-ops verify-user . <handle>` and complete the manual identity, content-sync, and app-managed site checks.
+7. Run Reconcile a second time. Require no generated diff and no deploy work before re-enabling normal automation and lifting the merge/release freeze.
+
+If any gate fails, disable all three workflows again. Restore the prior pilot desired-state and dependency revision, reconcile with the prior ops version, and redeploy the prior image tag/digest as one rollback pair. Verify the prior `/health` version and identity/content/site checks before re-enabling automation. Never restore only config or only an image.
+
 ## Stale deploy lock recovery
 
 Kamal intentionally leaves its remote deploy lock in place when a deployment is cancelled or interrupted. Confirm that no deployment for the user is still active before releasing the lock, then use the deploy workflow's explicit recovery input:
@@ -77,7 +105,7 @@ 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 verification notes
+## Canonical verification notes
 
 Use the verification script after deploy:
 
@@ -85,35 +113,31 @@ Use the verification script after deploy:
 bunx brains-ops verify-user . <handle>
 ```
 
-It checks every Rover preset:
+For every bundle posture it checks:
 
-- `https://<handle>.rizom.ai/health` should return `200`
-- unauthenticated `POST https://<handle>.rizom.ai/mcp` should return the expected auth failure
-- background jobs should not be repeatedly failing, except for expected missing optional integrations
+- `https://<handle>.rizom.ai/health` returns `200`;
+- unauthenticated `POST https://<handle>.rizom.ai/mcp` returns the expected auth failure;
+- background jobs are not repeatedly failing, except for missing optional integrations.
 
-Additional `rover:core` note:
-
-- Rover core is MCP-only; a bare `GET /` may return `401`, which does not indicate a bad deploy.
-
-For `preset: default`, the script also checks:
-
-- `https://<handle>.rizom.ai/` loads the browser/site surface
-- `https://<handle>.rizom.ai/cms` loads the CMS/login surface
+A `core`-only instance is MCP-only; a bare `GET /` may return `401` without indicating a bad deploy. When `site` is selected, verification also checks the browser and CMS/login surfaces.
 
 Manual checks that remain:
 
-- initial site build is correct for the expected content/theme
-- content repo exists and runtime sync is healthy beyond the basic `/health` response
-- passkey setup/handoff is completed from the setup email
+- initial app-managed site output is correct for the expected content/theme;
+- content repository identity and runtime sync are healthy;
+- passkey setup/handoff is completed from the setup email.
 
-## One-user `rover:default` baseline canary
+## One-user canonical site canary
 
 Run this before adding custom site/theme packages or rolling a larger browser/CMS-first cohort.
 
-1. Create or choose a canary cohort with the default preset:
+1. Create or choose a canary cohort with explicit bundles:
 
    ```yaml
-   presetOverride: default
+   bundles:
+     - core
+     - site
+     - publishing
    ```
 
 2. Add exactly one canary user to that cohort.
@@ -131,11 +155,7 @@ Run this before adding custom site/theme packages or rolling a larger browser/CM
 7. Ask the user to complete passkey setup from the setup email.
 8. Continue to visual customization only after the canary is healthy.
 
-Rollback:
-
-- move the canary back to a core cohort, or remove `presetOverride: default` from the cohort
-- reconcile generated outputs
-- rebuild/redeploy the affected user
+Rollback must restore the prior desired-state revision and prior runtime image together. Never pair canonical config with the retired image, or retired config with the canonical image.
 
 ## Hosted site and theme package contract
 
@@ -144,7 +164,7 @@ Start with the public [site mockup migration guide](https://github.com/rizom-ai/
 - A site package must default-export a valid `SitePackage` and use documented public APIs such as `@rizom/brain/site`.
 - A theme package must default-export its CSS as a string. Hosted custom themes currently use the `@rizom/*` scope so the fleet image installs them with the site package; `@brains/*` themes are bundled with `@rizom/brain`.
 - Site and custom theme packages must be public npm packages that install without registry credentials.
-- Site and theme packages publish on their own release cadences, independent of `@rizom/brain` and of each other. Hosted configuration resolves package names plus pinned versions into exact npm refs.
+- Site, theme, and brain packages publish independently. Hosted configuration requires exact site and external-theme version pins and never derives one package version from another.
 - Keep site structure and theme CSS in separate packages. Do not put private content or secrets in either package.
 
 Configure a user in `users/<handle>.yaml`:
@@ -152,22 +172,20 @@ Configure a user in `users/<handle>.yaml`:
 ```yaml
 siteOverride:
   package: "@rizom/site-example"
+  version: <exact-site-version>
   theme: "@rizom/theme-example"
-  themeVersion: <exact-theme-version> # required for @rizom/* themes
-  # version: <exact-site-version> # optional deliberate pin
+  themeVersion: <exact-theme-version>
 ```
 
-When `version` is omitted, it defaults to the user's effective brain version
-(cohort override first, then `pilot.yaml.brainVersion`). A `@rizom/*` theme
-always requires an explicit `themeVersion` — themes and sites version
-independently, so the theme's version is never inferred. A site override
-produces an isolated per-instance image; it never changes the fleet's shared
-default image.
+Missing external package versions fail desired-state validation. A site override
+produces an isolated per-instance image; it never changes the fleet's shared default
+image. Bundled `@brains/*` themes omit `themeVersion` because they are not installed as
+separate packages.
 
 ### Custom-package canary and rollback
 
 1. Confirm the exact site/theme versions are public-installable without npm credentials.
-2. Apply the package names to one healthy `rover:default` canary.
+2. Apply the exact package names and versions to one healthy canonical site canary.
 3. Reconcile the canary, push the generated output, and let build/deploy create its site image.
 4. Run `bunx brains-ops verify-user . <handle>`.
 5. Manually verify the site, theme, CMS, content sync, and passkey sign-in before adding more users.
@@ -246,31 +264,32 @@ Notes:
 - The ATProto app password is secret and belongs only in the encrypted per-user secret payload.
 - For smoke deployments, pin only the smoke cohort/user to the released brain version that contains ATProto support.
 
-## Discord bot token checklist
+## Discord application credential checklist
 
 Use this when enabling Discord for a pilot user.
 
 1. Pick the user handle (for example `smoke`).
 2. Open the Discord Developer Portal.
-3. Create a **new application** for that user's rover.
+3. Create a **new application** for that user's brain.
 4. Add a **Bot** to the application.
-5. Copy the bot token.
-6. Put that value in `.env` or `.env.local` in this repo as `DISCORD_BOT_TOKEN=...` while onboarding that user.
+5. Copy the bot token, application public key, and application ID.
+6. Put those values in `.env` or `.env.local` while onboarding that user:
+   - `DISCORD_BOT_TOKEN=...`
+   - `DISCORD_PUBLIC_KEY=...`
+   - `DISCORD_APPLICATION_ID=...`
 7. Keep `discord.enabled: true` in `users/<handle>.yaml` unless you explicitly want to disable the primary pilot interface.
-8. Encrypt the current per-user secret payload:
+8. Encrypt the current per-user credential payload:
    - `bunx brains-ops secrets:encrypt . <handle>`
 9. Reconcile/deploy the user or cohort:
-
-- `bunx brains-ops onboard . <handle>`
-- or `bunx brains-ops reconcile-cohort . <cohort>`
-
-11. In the Discord Developer Portal, generate an install URL and invite the bot to the right server.
-12. Send a test message in Discord and confirm the rover responds.
+   - `bunx brains-ops onboard . <handle>`
+   - or `bunx brains-ops reconcile-cohort . <cohort>`
+10. In the Discord Developer Portal, generate an install URL and invite the bot to the right server.
+11. Send a test message in Discord and confirm the brain responds.
 
 Notes:
 
-- Use **one bot token per user/rover**.
-- Do not reuse the same Discord bot token across multiple pilot users.
+- Use **one Discord application credential set per user/brain**.
+- Do not reuse the same Discord application across multiple pilot users.
 - Discord is the default pilot interface moving forward.
 - The encrypted `users/<handle>.secrets.yaml.age` file is the durable checked-in deploy input; your local env is only the operator staging source.
 - Direct MCP client access should use OAuth/passkey-capable clients where possible.