@rizom/ops 0.2.0-alpha.211 → 0.2.0-alpha.213

package/dist/schema.d.ts

@@ -51,7 +51,7 @@ declare const atprotoSchema: z.ZodObject<{
 }>;
 declare const siteOverrideSchema: z.ZodObject<{
     package: z.ZodString;
-    version: typeof exactVersionSchema;
+    version: z.ZodOptional<typeof exactVersionSchema>;
     theme: z.ZodOptional<z.ZodString>;
 }>;
 declare const playbooksSchema: z.ZodObject<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rizom/ops",
-  "version": "0.2.0-alpha.211",
+  "version": "0.2.0-alpha.213",
   "description": "Operator CLI for managing private brain fleet registry repos",
   "keywords": [
     "brains",

package/templates/rover-pilot/README.md

@@ -30,8 +30,8 @@ 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 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.
+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 a push changes only deploy contract files, CI prints `No affected user configs; skipping deploy.` and stops before Kamal.
 
 ## Commands

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

@@ -34,7 +34,7 @@
       - 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.
+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.
 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

@@ -14,21 +14,26 @@ Treat these as checked-in deploy artifacts in the pilot repo:
 `.env.schema` is the single source of truth for required and sensitive deploy vars.
 The deploy scripts and workflows should read from that contract instead of inventing a second list.
 
-The shared pilot image tag is `brain-${brainVersion}`:
+The default pilot image tag is `brain-${brainVersion}`:
 
-- build publishes `brain-${brainVersion}`
+- build publishes `brain-${brainVersion}` for users without a site override
+- a site override gets an isolated `brain-${brainVersion}-sites-${packageHash}` image
 - generated `users/<handle>/.env` carries `BRAIN_VERSION=<brainVersion>`
-- deploy sets `VERSION=brain-${brainVersion}`
+- build and deploy derive the same effective image tag from the resolved registry
 
 ## Version bump flow
 
 When `pilot.yaml.brainVersion` changes and you push:
 
-1. build publishes the new shared image tag
+1. build publishes the new default image and any required site images
 2. reconcile refreshes generated `users/<handle>/.env`
 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.
+
 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.
@@ -132,6 +137,41 @@ Rollback:
 - reconcile generated outputs
 - rebuild/redeploy the affected user
 
+## Hosted site and theme package contract
+
+Start with the public [site mockup migration guide](https://github.com/rizom-ai/brains/blob/main/docs/site-mockup-migration.md), then apply these hosted-fleet requirements:
+
+- 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.
+- Publish packages at the same exact version as the compatible `@rizom/brain` release. Hosted configuration resolves package names plus the effective version into exact npm refs.
+- 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`:
+
+```yaml
+siteOverride:
+  package: "@rizom/site-example"
+  theme: "@rizom/theme-example"
+  # version: <exact-brain-version> # optional deliberate pin
+```
+
+When `version` is omitted, it defaults to the user's effective brain version
+(cohort override first, then `pilot.yaml.brainVersion`). A site override produces
+an isolated per-instance image; it never changes the fleet's shared default
+image.
+
+### 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.
+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.
+
+To roll back, remove or change `siteOverride`, reconcile, and redeploy that user.
+The default image and other users remain untouched.
+
 ## Setup email checklist
 
 Use this for browser/CMS-first users who should receive their own first-passkey setup link by email.