@rizom/ops 0.2.0-alpha.8 → 0.2.0-alpha.80

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

@@ -1,17 +1,43 @@
 # Onboarding Checklist
 
 1. Run `bun install` so the repo uses its pinned `@rizom/ops` version.
-2. Fill in `pilot.yaml`.
-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 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.
+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 `contentRepoAdminToken`
+   - use different tokens for `contentRepoAdminToken` and `gitSyncToken`: admin creates/checks content repos; sync is used by runtime directory-sync
+   - confirm `agePublicKey`
+4. Run `bunx brains-ops user:add <repo> <handle> --cohort <cohort>`.
+   - Discord is enabled by default for pilot users.
+   - if the user should be an anchor there, 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.
+   - For browser/CMS-first onboarding, add `setup.delivery: email` and `setup.email` to the user 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), 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 contract:
+    - all presets:
+      - `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 expected missing optional integrations
+    - for `presetOverride: default` users:
+      - `https://<handle>.rizom.ai/` loads the browser/site surface
+      - `https://<handle>.rizom.ai/cms` loads the CMS/login surface
+      - initial site build completes
+      - content repo exists and runtime sync is healthy
+      - passkey setup/handoff is completed
+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. For Discord users, hand the Discord setup details to the user. For email-setup users, confirm they received the setup email and completed passkey registration.
+16. Hand over the browser defaults:
+    - Dashboard: `https://<handle>.rizom.ai/`
+    - CMS: `https://<handle>.rizom.ai/cms`
+    - GitHub token guidance for CMS access to the user's private content repo
+17. If they need direct client access, use OAuth/passkey-capable clients where possible.
+18. 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.
+19. Send `docs/user-onboarding.md` to the user as the pilot handoff guide.

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

@@ -35,14 +35,21 @@ They are scaffolded from `@rizom/ops`, then versioned in this repo like any othe
 
 ## Bootstrap flow
 
+For this fleet, operator-local secret material remains the source of truth during onboarding and rotation. The repo stores encrypted per-user secrets, not raw values.
+
 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>`
+1. `bunx brains-ops age-key:bootstrap <repo> --push-to gh`
+2. `bunx brains-ops ssh-key:bootstrap <repo> --push-to gh`
+3. `bunx brains-ops cert:bootstrap <repo> --push-to gh`
+4. `bunx brains-ops secrets:encrypt <repo> <handle>`
+5. `bunx brains-ops onboard <repo> <handle>`
+
+`age-key:bootstrap` keeps a repo-local canonical age identity under `.brains-ops/age/identity.txt`, writes the matching public recipient to `pilot.yaml.agePublicKey`, and can push the private key to GitHub as `AGE_SECRET_KEY`.
+
+The shared cert bootstrap writes local cert artifacts under `.brains-ops/certs/shared/`, which stays repo-local and ignored by git.
 
-`brains-ops cert:bootstrap` writes local cert artifacts under `.brains-ops/`, which stays repo-local and ignored by git.
+Preview hosts use the shape `<handle>-preview.rizom.ai`, so one wildcard origin cert for `*.rizom.ai` covers both the primary and preview hosts for every pilot user.
 
 ## Upgrading operator behavior
 
@@ -53,15 +60,127 @@ 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 verification notes
 
-Rover core is MCP-only. Do not expect the bare domain to serve a website.
+Use the verification script after deploy:
 
-Use these checks after deploy:
+```sh
+bunx brains-ops verify-user . <handle>
+```
+
+It checks every Rover preset:
 
 - `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
+- 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
+
+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
+
+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
+
+## One-user `rover:default` baseline 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:
+
+   ```yaml
+   presetOverride: default
+   ```
+
+2. Add exactly one canary user to that cohort.
+3. For browser/CMS-first onboarding, configure setup email in `users/<handle>.yaml`:
+
+   ```yaml
+   setup:
+     delivery: email
+     email: user@example.com
+   ```
+
+4. Encrypt the user's secrets and commit only the `.age` file.
+5. Run `bunx brains-ops onboard . <handle>`.
+6. Run `bunx brains-ops verify-user . <handle>` with no custom site/theme overrides.
+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
+
+## Setup email checklist
+
+Use this for browser/CMS-first users who should receive their own first-passkey setup link by email.
+
+1. Add setup delivery to the user file:
+
+   ```yaml
+   setup:
+     delivery: email
+     email: user@example.com
+   ```
+
+2. Configure these GitHub Secrets before deploy:
+   - `SETUP_EMAIL_API_KEY`
+   - `SETUP_EMAIL_FROM`
+
+3. Reconcile/deploy the user or cohort:
+   - `bunx brains-ops onboard . <handle>`
+   - or `bunx brains-ops reconcile-cohort . <cohort>`
+
+4. Verify the generated `users/<handle>/brain.yaml` contains `auth-service.setupEmail` and `email-resend` config.
+5. Ask the user to complete passkey setup from the email link, then use:
+   - Dashboard: `https://<handle>.rizom.ai/`
+   - CMS: `https://<handle>.rizom.ai/cms`
+
+Notes:
+
+- The setup URL is generated and sent by the running brain; operators should not scrape logs or SSH into the instance to retrieve it.
+- The auth service owns setup email dedupe. It should not resend for the same persisted setup token after restart, but should retry failed delivery and resend after token rotation.
+- `SETUP_EMAIL_FROM` is not marked required because fleets without email setup can omit it, but it is required for users with `setup.delivery: email`.
+
+## Discord bot token 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.
+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.
+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:
+   - `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.
+
+Notes:
+
+- Use **one bot token per user/rover**.
+- Do not reuse the same Discord bot token 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.
+- When explaining the content workflow, describe it first as a normal **git repo** of **markdown/text files**.
+- Position **Obsidian** as optional: it is just one possible editor for those same files, not the default requirement.
 
 ## Recovery notes