@rizom/ops 0.2.0-alpha.243 → 0.2.0-alpha.245

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, lists both passes' changed files, and must report second-pass zero drift. Reconciliation owns generated per-user config; only `render` owns the observational `views/users.md` projection.
+
+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 per-user config commit. It must not rewrite `views/users.md`, and 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>`, render observed fleet status, and complete the manual identity, content-sync, and app-managed site checks.
+7. Run Reconcile a second time. Require no reconciler-owned generated diff and no deploy work before re-enabling normal automation and lifting the merge/release freeze. Observed status rendering remains separate from this convergence gate.
+
+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.

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

@@ -1,119 +1,90 @@
-# Welcome to Rover
+# Welcome to your brain
 
 ---
 
 Most of us have more thinking happening than we can hold onto. Ideas show up in the wrong moment, notes land in five different places, and half of what you've figured out is effectively invisible by the time you need it again.
 
-Rover is built for that problem. It's a private space where your thinking accumulates — notes, links, fragments, half-formed ideas — and an AI that can work with all of it. Find things you saved months ago. Connect dots across topics. Turn a rough note into a draft. The more you put in, the more useful it gets. And if another Rover user is in your network, your Rovers can talk to each other — share knowledge, work on something together — just by asking.
+Your brain is a private space where that thinking accumulates — notes, links, fragments, and half-formed ideas — plus an AI that can work with all of it. It can find things you saved months ago, connect topics, or help turn a rough note into a draft. The more useful material you add, the more useful it becomes.
 
 ---
 
-## What Rover is
+## What it is
 
-Rover is your private knowledge companion. It holds your notes, links, and ideas — and helps you think with them, not just store them.
+Your brain is a private knowledge companion. It holds your notes, links, and ideas and helps you think with them, not just store them.
 
-Ask it a question and it searches what you've saved. Give it a fragment of thinking and it can help you turn it into something.
-
----
+Ask a question and it searches what you've saved. Give it a fragment of thinking and it can help develop it.
 
 ## Getting in
 
-We'll send you a personal URL — something like `https://<handle>.rizom.ai/`.
-
-When you open it for the first time, you'll be asked to set a passkey. Do that once and you're in. No passwords to remember.
+We'll send you a personal URL such as `https://<handle>.rizom.ai/`.
 
-From there, your three main interfaces are:
+The first time you open it, you will be asked to set a passkey. No password is required after that.
 
-- **Chat** (`/chat`) — where you talk to Rover
-- **Dashboard** (`/`) — an overview of your Rover
-- **CMS** (`/cms`) — a browser editor for your content
+Your main interfaces are:
 
-Start with Chat. Everything else follows from there.
+- **Chat** (`/chat`) — talk to your brain;
+- **Dashboard/site** (`/`) — the configured browser surface;
+- **CMS** (`/cms`) — edit durable content in a browser.
 
----
+Start with Chat.
 
 ## Your first five minutes
 
-1. Open your Chat URL. A good first message:
-   > Help me save my first note.
-2. Save something — a thought, a link, an idea. Doesn't need to be polished.
-3. Ask Rover about it. See what comes back.
-
-That loop — save, ask, get something useful back — is the core of how Rover works.
-
----
-
-## The Chat and the CMS: when to use which
-
-**Chat** is for thinking out loud, asking questions, saving things quickly, and using Rover as a day-to-day thinking partner.
+1. Open Chat and say: _Help me save my first note._
+2. Save a thought, link, or idea. It does not need to be polished.
+3. Ask about it and inspect what comes back.
 
-**CMS** is for when you want to deliberately create or edit content — browsing your notes, making clean edits, working more like an editor than a conversationalist.
+That save–ask–use loop is the core workflow.
 
-Most people spend most of their time in Chat. The CMS becomes useful once you have something worth editing.
+## Chat or CMS?
 
----
-
-## Other ways to chat with Rover
+**Chat** is for thinking aloud, asking questions, saving things quickly, and day-to-day work.
 
-`/chat` is the primary interface, but Rover can also be reached through messaging platforms. Discord is tested and working. Slack, WhatsApp Business, and similar should work out of the box — we'll send setup steps if that's part of your configuration.
+**CMS** is for deliberate browsing and editing. It becomes more useful as your content grows.
 
-**Talking to another Rover**
+## Other interfaces and peer brains
 
-If you know another Rover user, you can add them to your contacts and call their Rover directly from your chat.
+Chat is primary. Your configured posture may also enable Discord, Slack, MCP clients, or agent-to-agent calls. We will send setup steps for integrations enabled for your instance.
 
-- To add: _Add jane.rizom.ai to my contacts._
-- To call: _Call jane.rizom.ai and ask [your question]._
-  You'll need their address — in the format `name.rizom.ai` — which they can share with you directly.
+With permission, you can save another participant's brain as a contact and call it by its shared address:
 
----
+- _Add jane.rizom.ai to my contacts._
+- _Call jane.rizom.ai and ask [your question]._
 
-## Connecting Rover to other tools
+## Connecting other tools
 
-Rover can connect to external tools via MCP — a standard protocol that works in two directions: agentic AI clients (like Claude Desktop) can use it to talk to Rover, and Rover can use it to talk to productivity tools like Notion or Linear.
+MCP is a standard protocol that lets compatible AI clients use your brain's tools and lets configured integrations connect to external services. If MCP is part of your setup, we will send specific instructions alongside your URL.
 
-Plugins exist for a number of tools already, and new ones can be built quickly in response to what you actually need. If there's a tool you'd want Rover to connect to, tell us.
+## Common questions
 
-If MCP is part of your setup, we'll send specific instructions alongside your URL.
-
----
+**How do I access my data?**
 
-## A few common questions
+Use the CMS. If your cohort includes GitHub access, the same durable markdown also lives in a private repository.
 
-**How do I access my data?**
-Your primary interface is the CMS (`/cms`), where you can browse and edit everything you've saved. If you're set up with GitHub access, your content also lives in a private repository you can access directly.
+**Does it search the public internet?**
 
-**Does Rover connect to the internet?**
-No — and that's intentional. Rover works with what you've put into it, not with whatever the internet currently says. That means its answers are grounded in your actual knowledge base, not in generic search results.
+Not by default. Answers are grounded in your own knowledge unless an explicitly configured integration provides another source.
 
 **What does this cost?**
-Nothing during the pilot. We cover hosting costs while you're part of the programme.
 
----
+Nothing during the pilot; hosting is covered by the programme.
 
 ## This is a pilot
 
-Rover works. But it's not finished.
-
-You'll hit rough edges. Some things you try won't work. Some things you expect to be there won't be yet. That's normal — and it's actually why you're here.
+The product works, but it is not finished. You will encounter rough edges and missing behavior. If something breaks or falls short, tell us what you tried, what you expected, and what happened.
 
-There's a ceiling on how much Rover can improve without real people using it on real problems. We've reached that ceiling on our own. Your usage is what lets the product become what it's capable of becoming. A single Rover in isolation can only do so much — the network only becomes real when there are enough active, populated Rovers in it.
-
-Rover has a built-in wishlist. If you ask it to do something it can't do yet, it should tell you clearly and log the request — that goes back to us as a signal for where the product needs to go next.
-
-When something breaks or falls short, tell us: what you were trying to do, what you expected, and what happened instead.
-
----
+A built-in wishlist can record unsupported requests as product feedback.
 
 ## Your access details
 
-When we onboard you, we'll send something like:
+We will send details in this shape:
 
-```
+```text
 Chat URL: https://<handle>.rizom.ai/chat
 Dashboard URL: https://<handle>.rizom.ai/
 CMS URL: https://<handle>.rizom.ai/cms
-Discord: yes/no — setup steps below if yes
-MCP: enabled/not enabled — details below if enabled
+Discord: yes/no — setup steps if enabled
+MCP: enabled/not enabled — setup details if enabled
 ```
 
-If anything is unclear, reply with what you're seeing and we'll help.
+If anything is unclear, reply with what you see and we will help.

package/templates/rover-pilot/pilot.yaml

@@ -1,10 +1,9 @@
-schemaVersion: 1
 brainVersion: 0.1.1-alpha.14
-model: rover
 githubOrg: <github-org>
 contentRepoPrefix: rover-
 domainSuffix: .rizom.ai
-preset: core
+bundles:
+  - core
 aiApiKey: AI_API_KEY
 gitSyncToken: GIT_SYNC_TOKEN
 contentRepoAdminToken: CONTENT_REPO_ADMIN_TOKEN