@rizom/ops 0.2.0-alpha.3 → 0.2.0-alpha.300

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +44 -3
  2. package/dist/age-key-bootstrap.d.ts +17 -0
  3. package/dist/brains-ops.js +453 -173
  4. package/dist/cert-bootstrap.d.ts +24 -0
  5. package/dist/content-repo-ref.d.ts +10 -0
  6. package/dist/content-repo.d.ts +13 -0
  7. package/dist/default-user-runner.d.ts +1 -1
  8. package/dist/deploy.js +99 -166
  9. package/dist/directory-sync-stress-system.d.ts +75 -0
  10. package/dist/directory-sync-stress.d.ts +107 -0
  11. package/dist/entries/deploy.d.ts +3 -2
  12. package/dist/images.d.ts +79 -0
  13. package/dist/index.d.ts +11 -0
  14. package/dist/index.js +523 -152
  15. package/dist/legacy-pilot-migration.d.ts +11 -0
  16. package/dist/load-registry.d.ts +74 -7
  17. package/dist/observed-status.d.ts +12 -0
  18. package/dist/onboard-user.d.ts +2 -2
  19. package/dist/origin-ca.d.ts +1 -0
  20. package/dist/parse-args.d.ts +2 -9
  21. package/dist/preview-domain.d.ts +9 -0
  22. package/dist/push-secrets.d.ts +2 -0
  23. package/dist/push-target.d.ts +1 -0
  24. package/dist/reconcile-all.d.ts +2 -2
  25. package/dist/reconcile-cohort.d.ts +2 -2
  26. package/dist/reconcile-dry-run.d.ts +9 -0
  27. package/dist/reconcile-lib.d.ts +4 -2
  28. package/dist/run-command.d.ts +19 -4
  29. package/dist/run-subprocess.d.ts +1 -0
  30. package/dist/schema.d.ts +119 -70
  31. package/dist/secrets-encrypt.d.ts +26 -0
  32. package/dist/secrets-push.d.ts +2 -5
  33. package/dist/ssh-key-bootstrap.d.ts +1 -0
  34. package/dist/stage-legacy-crossover.d.ts +20 -0
  35. package/dist/stress-command.d.ts +14 -0
  36. package/dist/stress-git-checkout.d.ts +21 -0
  37. package/dist/stress-health-monitor.d.ts +46 -0
  38. package/dist/upgrade.d.ts +10 -0
  39. package/dist/user-add.d.ts +15 -0
  40. package/dist/user-runner.d.ts +5 -0
  41. package/dist/verify-user.d.ts +22 -0
  42. package/package.json +47 -40
  43. package/templates/rover-pilot/.env.schema +28 -2
  44. package/templates/rover-pilot/.github/actions/varlock-env/action.yml +47 -0
  45. package/templates/rover-pilot/.github/workflows/build.yml +71 -17
  46. package/templates/rover-pilot/.github/workflows/deploy.yml +110 -45
  47. package/templates/rover-pilot/.github/workflows/directory-sync-stress.yml +119 -0
  48. package/templates/rover-pilot/.github/workflows/reconcile.yml +23 -3
  49. package/templates/rover-pilot/.github/workflows/upgrade.yml +104 -0
  50. package/templates/rover-pilot/README.md +20 -7
  51. package/templates/rover-pilot/deploy/scripts/decrypt-user-secrets.ts +139 -0
  52. package/templates/rover-pilot/deploy/scripts/helpers.ts +3 -0
  53. package/templates/rover-pilot/deploy/scripts/install-health-watchdog.ts +144 -0
  54. package/templates/rover-pilot/deploy/scripts/provision-server.ts +1 -1
  55. package/templates/rover-pilot/deploy/scripts/resolve-deploy-handles.ts +15 -4
  56. package/templates/rover-pilot/deploy/scripts/resolve-missing-images.ts +13 -0
  57. package/templates/rover-pilot/deploy/scripts/resolve-user-config.ts +49 -14
  58. package/templates/rover-pilot/deploy/scripts/sync-content-repo.ts +183 -0
  59. package/templates/rover-pilot/deploy/scripts/update-dns.ts +14 -4
  60. package/templates/rover-pilot/deploy/scripts/validate-secrets.ts +12 -1
  61. package/templates/rover-pilot/docs/canonical-crossover-record.md +104 -0
  62. package/templates/rover-pilot/docs/onboarding-checklist.md +39 -8
  63. package/templates/rover-pilot/docs/operator-playbook.md +298 -9
  64. package/templates/rover-pilot/docs/user-onboarding.md +90 -0
  65. package/templates/rover-pilot/package.json +3 -0
  66. package/templates/rover-pilot/pilot.yaml +5 -3
  67. package/templates/rover-pilot/users/alice.yaml +5 -1
  68. package/dist/user-secret-names.d.ts +0 -6
  69. package/templates/rover-pilot/.kamal/hooks/pre-deploy +0 -9
  70. package/templates/rover-pilot/deploy/Dockerfile +0 -15
  71. package/templates/rover-pilot/deploy/kamal/deploy.yml +0 -39
@@ -9,38 +9,327 @@ Treat these as checked-in deploy artifacts in the pilot repo:
9
9
  - `deploy/scripts/`
10
10
  - `.github/workflows/build.yml`
11
11
  - `.github/workflows/deploy.yml`
12
+ - `.github/workflows/directory-sync-stress.yml`
12
13
  - `.github/workflows/reconcile.yml`
13
14
 
14
15
  `.env.schema` is the single source of truth for required and sensitive deploy vars.
15
16
  The deploy scripts and workflows should read from that contract instead of inventing a second list.
16
17
 
17
- The shared pilot image tag is `brain-${brainVersion}`:
18
+ The default pilot image tag is `brain-${brainVersion}`:
18
19
 
19
- - build publishes `brain-${brainVersion}`
20
+ - build publishes `brain-${brainVersion}` for users without a site override
21
+ - a site override gets an isolated `brain-${brainVersion}-sites-${packageHash}` image
20
22
  - generated `users/<handle>/.env` carries `BRAIN_VERSION=<brainVersion>`
21
- - deploy sets `VERSION=brain-${brainVersion}`
23
+ - build and deploy derive the same effective image tag from the resolved registry
22
24
 
23
25
  ## Version bump flow
24
26
 
25
27
  When `pilot.yaml.brainVersion` changes and you push:
26
28
 
27
- 1. build publishes the new shared image tag
29
+ 1. build publishes the new default image and any required site images
28
30
  2. reconcile refreshes generated `users/<handle>/.env`
29
31
  3. deploy runs for handles whose generated config changed
30
32
  4. generated file commits happen once in a final aggregation step after the deploy matrix finishes
31
33
 
34
+ Every external site and theme package has its own exact version pin. A cohort or
35
+ pilot brain-version bump never changes those package versions implicitly; update each
36
+ pin deliberately from reviewed package and image evidence.
37
+
32
38
  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.`
33
39
 
34
40
  They are scaffolded from `@rizom/ops`, then versioned in this repo like any other deploy contract.
35
41
 
42
+ ## Canonical contract crossover maintenance window
43
+
44
+ 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.
45
+
46
+ Before the window, record and review:
47
+
48
+ - the prior pilot commit and exact `@rizom/ops` version;
49
+ - every prior runtime image tag and immutable digest;
50
+ - the reviewed canonical pilot commit;
51
+ - the exact unified `@rizom/brain` and `@rizom/ops` versions;
52
+ - every unified image tag and immutable digest;
53
+ - canary-first rollout order, followed by the remaining cohorts;
54
+ - expected `/health/operate` version, unauthenticated MCP response, site marker, and content repository identity for each posture.
55
+
56
+ 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.
57
+
58
+ During the approved window:
59
+
60
+ 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`.
61
+ 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.
62
+ 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.
63
+ 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.
64
+ 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.
65
+ 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.
66
+ 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.
67
+
68
+ 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/operate` version and identity/content/site checks before re-enabling automation. Never restore only config or only an image.
69
+
70
+ ## Directory-sync stress gate
71
+
72
+ Use the manual `Directory Sync Stress` workflow only against a disposable smoke user. It refuses a target unless the handle, domain, and content repository all identify smoke, the confirmation input exactly matches `stress:<handle>`, and the user desired state declares the hermetic posture below. Reconcile and deploy this posture before running the workload:
73
+
74
+ ```yaml
75
+ embeddingEnabled: false
76
+ topicExtractionEnabled: false
77
+ ```
78
+
79
+ Before authorizing a workload, dispatch the workflow once with `verify_only: true`. That mode loads the same Bitwarden/Varlock content credential, clones the smoke content repository, and runs `git push --dry-run` against a temporary stress ref. It creates no ref, performs no content write, does not contact the deployed runtime, and skips cleanup because no probes were created.
80
+
81
+ Profiles are deterministic and reversible:
82
+
83
+ - `regression`: 20 probes;
84
+ - `load`: ramps to 350 probes, updates all, renames 100, updates again, then deletes all;
85
+ - `stress`: ramps to 700 probes and renames 200 before cleanup.
86
+
87
+ The workflow loads operator credentials through Bitwarden/Varlock, but it is separate from Deploy and cannot deploy an image. It creates a rollback branch before the first content write, gates on health timeouts, watchdog restarts, and external AI usage during the monitored workload window, preserves warmup and cleanup samples as evidence, uploads JSON/Markdown/runtime artifacts, and runs an independent idempotent cleanup job with `if: always()`. Once cleanup confirms that no probes remain, it also prunes retained `ops/directory-sync-stress-backup-*` branches; if probes remain, the branches stay available for recovery.
88
+
89
+ Treat any gated health failure, restart, OOM, residual probe, or entity-baseline drift as a failed gate. Do not restart the target during measurement. Recovery is a separate operator action after evidence collection.
90
+
91
+ ## Stale deploy lock recovery
92
+
93
+ 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:
94
+
95
+ ```sh
96
+ gh workflow run Deploy --ref main \
97
+ -f handle=<handle> \
98
+ -f release_stale_lock=true
99
+ ```
100
+
101
+ Recovery is opt-in and scoped to one handle. Normal push, reconcile, and manual deploy runs never remove a lock automatically.
102
+
103
+ ## Bootstrap flow
104
+
105
+ 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.
106
+
107
+ For a new pilot user, the operator bootstrap order is:
108
+
109
+ 1. `bunx brains-ops age-key:bootstrap <repo> --push-to gh`
110
+ 2. `bunx brains-ops ssh-key:bootstrap <repo> --push-to gh`
111
+ 3. `bunx brains-ops cert:bootstrap <repo> --push-to gh`
112
+ 4. `bunx brains-ops secrets:encrypt <repo> <handle>`
113
+ 5. `bunx brains-ops onboard <repo> <handle>`
114
+
115
+ `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`.
116
+
117
+ The shared cert bootstrap writes local cert artifacts under `.brains-ops/certs/shared/`, which stays repo-local and ignored by git.
118
+
119
+ 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.
120
+
36
121
  ## Upgrading operator behavior
37
122
 
38
- When `@rizom/ops` changes the scaffolded deploy contract:
123
+ The pilot repository pins `@rizom/ops` in `package.json`. The scheduled and manually dispatched Upgrade workflow owns routine upgrades to that pin. It refreshes the scaffold on a branch and opens a reviewable PR; it does not change runtime desired state or authorize a deployment.
124
+
125
+ Because scaffold refreshes can update `.github/workflows/*`, the workflow must not push with its Actions `GITHUB_TOKEN`. Configure a dedicated GitHub App:
126
+
127
+ 1. Install it only on this pilot repository.
128
+ 2. Grant repository permissions `Contents: Read and write`, `Pull requests: Read and write`, and `Workflows: Read and write`; grant nothing else.
129
+ 3. Store its App ID as the repository Actions variable `OPS_UPGRADE_APP_ID`.
130
+ 4. Store its private key as the repository Actions secret `OPS_UPGRADE_APP_PRIVATE_KEY`.
131
+
132
+ The workflow explicitly requests only those three permissions. Checkout persists no credential. After the freshly published `@rizom/ops` finishes, the workflow checks whether it produced a change; only then does it mint a short-lived, repository-scoped App token for the push-and-open-PR steps. A credential that can rewrite `.github/workflows/` therefore does not exist while upgraded package code runs.
133
+
134
+ If `OPS_UPGRADE_APP_ID` is unset, or token creation, branch push, or PR creation fails, the run stops with a non-zero status. Repair the CI credential path; never fall back to an operator's personal SSH key or token.
135
+
136
+ Adopting this credential flow in an existing pilot repository requires one explicitly reviewed bootstrap PR because the old Upgrade workflow cannot update itself. After that merge, routine upgrades run entirely in CI:
137
+
138
+ 1. dispatch Upgrade with an exact version, or let its schedule select `latest`;
139
+ 2. review the generated package, lockfile, deploy-script, and workflow diff;
140
+ 3. merge the upgrade PR only after its checks pass;
141
+ 4. change runtime desired state separately through the approved canary or fleet rollout flow.
142
+
143
+ ## Canonical verification notes
144
+
145
+ Use the verification script after deploy:
146
+
147
+ ```sh
148
+ bunx brains-ops verify-user . <handle>
149
+ ```
150
+
151
+ For every bundle posture it checks:
152
+
153
+ - `https://<handle>.rizom.ai/health/operate` returns `200`;
154
+ - unauthenticated `POST https://<handle>.rizom.ai/mcp` returns the expected auth failure;
155
+ - background jobs are not repeatedly failing, except for missing optional integrations.
156
+
157
+ 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.
158
+
159
+ Manual checks that remain:
160
+
161
+ - initial app-managed site output is correct for the expected content/theme;
162
+ - content repository identity and runtime sync are healthy;
163
+ - passkey setup/handoff is completed from the setup email.
164
+
165
+ ## One-user canonical site canary
166
+
167
+ Run this before adding custom site/theme packages or rolling a larger browser/CMS-first cohort.
168
+
169
+ 1. Create or choose a canary cohort with explicit bundles:
170
+
171
+ ```yaml
172
+ bundles:
173
+ - core
174
+ - site
175
+ - publishing
176
+ ```
177
+
178
+ 2. Add exactly one canary user to that cohort.
179
+ 3. For browser/CMS-first onboarding, configure setup email in `users/<handle>.yaml`:
180
+
181
+ ```yaml
182
+ setup:
183
+ delivery: email
184
+ email: user@example.com
185
+ ```
186
+
187
+ 4. Encrypt the user's secrets and commit only the `.age` file.
188
+ 5. Run `bunx brains-ops onboard . <handle>`.
189
+ 6. Run `bunx brains-ops verify-user . <handle>` with no custom site/theme overrides.
190
+ 7. Ask the user to complete passkey setup from the setup email.
191
+ 8. Continue to visual customization only after the canary is healthy.
192
+
193
+ 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.
194
+
195
+ ## Hosted site and theme package contract
196
+
197
+ 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:
198
+
199
+ - A site package must default-export `defineSite(...)` and import its authoring API only from `@rizom/site`.
200
+ - 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`.
201
+ - Site and custom theme packages must be public npm packages that install without registry credentials.
202
+ - 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.
203
+ - Keep site structure and theme CSS in separate packages. Do not put private content or secrets in either package.
204
+
205
+ Configure a user in `users/<handle>.yaml`:
206
+
207
+ ```yaml
208
+ siteOverride:
209
+ package: "@rizom/site-example"
210
+ version: <exact-site-version>
211
+ theme: "@rizom/theme-example"
212
+ themeVersion: <exact-theme-version>
213
+ ```
214
+
215
+ Missing external package versions fail desired-state validation. A site override
216
+ produces an isolated per-instance image; it never changes the fleet's shared default
217
+ image. Bundled `@brains/*` themes omit `themeVersion` because they are not installed as
218
+ separate packages.
219
+
220
+ ### Custom-package canary and rollback
221
+
222
+ 1. Confirm the exact site/theme versions are public-installable without npm credentials.
223
+ 2. Apply the exact package names and versions to one healthy canonical site canary.
224
+ 3. Reconcile the canary, push the generated output, and let build/deploy create its site image.
225
+ 4. Run `bunx brains-ops verify-user . <handle>`.
226
+ 5. Manually verify the site, theme, CMS, content sync, and passkey sign-in before adding more users.
227
+
228
+ To roll back, remove or change `siteOverride`, reconcile, and redeploy that user.
229
+ The default image and other users remain untouched.
230
+
231
+ ## Setup email checklist
232
+
233
+ Use this for browser/CMS-first users who should receive their own first-passkey setup link by email.
234
+
235
+ 1. Add setup delivery to the user file:
236
+
237
+ ```yaml
238
+ setup:
239
+ delivery: email
240
+ email: user@example.com
241
+ ```
242
+
243
+ 2. Configure these GitHub Secrets before deploy:
244
+ - `SETUP_EMAIL_API_KEY`
245
+ - `SETUP_EMAIL_FROM`
246
+
247
+ 3. Reconcile/deploy the user or cohort:
248
+ - `bunx brains-ops onboard . <handle>`
249
+ - or `bunx brains-ops reconcile-cohort . <cohort>`
250
+
251
+ 4. Verify the generated `users/<handle>/brain.yaml` contains `auth-service.setupEmail` and `email` interface config.
252
+ 5. Ask the user to complete passkey setup from the email link, then use:
253
+ - Dashboard: `https://<handle>.rizom.ai/`
254
+ - CMS: `https://<handle>.rizom.ai/cms`
255
+
256
+ Notes:
257
+
258
+ - The setup URL is generated and sent by the running brain; operators should not scrape logs or SSH into the instance to retrieve it.
259
+ - 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.
260
+ - `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`.
261
+
262
+ ## AT Protocol smoke/config checklist
263
+
264
+ Use this when enabling AT Protocol publishing for a single pilot user.
265
+
266
+ 1. Add the public PDS identifier to the user file. Prefer the account DID as
267
+ the identifier — it survives handle changes. Add `accountDid` too when the
268
+ member wants their handle verified against their subdomain
269
+ (`@<handle>.<domainSuffix>`): the brain then serves it at
270
+ `/.well-known/atproto-did` and Bluesky's "I have my own domain" HTTP
271
+ verification passes with no DNS records.
272
+
273
+ ```yaml
274
+ atproto:
275
+ identifier: did:plc:example123
276
+ accountDid: did:plc:example123
277
+ ```
278
+
279
+ Only for the PDS account designated by the protocol authority's `_lexicon`
280
+ DNS TXT record, also set `lexiconAuthority: true`. Every other fleet user
281
+ must omit it.
282
+
283
+ 2. Put the app password in `users/<handle>.secrets.yaml`:
284
+
285
+ ```yaml
286
+ atprotoAppPassword: <app-password>
287
+ ```
288
+
289
+ 3. Encrypt the per-user secret payload:
290
+ - `bunx brains-ops secrets:encrypt . <handle>`
291
+ 4. Reconcile/deploy the user or cohort:
292
+ - `bunx brains-ops onboard . <handle>`
293
+ - or `bunx brains-ops reconcile-cohort . <cohort>`
294
+ 5. Verify the generated `users/<handle>/brain.yaml` contains `plugins.atproto.identifier` (plus `accountDid` and `lexiconAuthority` when configured) and `appPassword: ${ATPROTO_APP_PASSWORD}`.
295
+
296
+ Notes:
297
+
298
+ - The ATProto identifier and authority flag are public instance config and belong in `users/<handle>.yaml`. Only the DNS-designated authority account may set `lexiconAuthority: true`.
299
+ - The ATProto app password is secret and belongs only in the encrypted per-user secret payload.
300
+ - For smoke deployments, pin only the smoke cohort/user to the released brain version that contains ATProto support.
301
+
302
+ ## Discord application credential checklist
303
+
304
+ Use this when enabling Discord for a pilot user.
305
+
306
+ 1. Pick the user handle (for example `smoke`).
307
+ 2. Open the Discord Developer Portal.
308
+ 3. Create a **new application** for that user's brain.
309
+ 4. Add a **Bot** to the application.
310
+ 5. Copy the bot token, application public key, and application ID.
311
+ 6. Put those values in `.env` or `.env.local` while onboarding that user:
312
+ - `DISCORD_BOT_TOKEN=...`
313
+ - `DISCORD_PUBLIC_KEY=...`
314
+ - `DISCORD_APPLICATION_ID=...`
315
+ 7. Keep `discord.enabled: true` in `users/<handle>.yaml` unless you explicitly want to disable the primary pilot interface.
316
+ 8. Encrypt the current per-user credential payload:
317
+ - `bunx brains-ops secrets:encrypt . <handle>`
318
+ 9. Reconcile/deploy the user or cohort:
319
+ - `bunx brains-ops onboard . <handle>`
320
+ - or `bunx brains-ops reconcile-cohort . <cohort>`
321
+ 10. In the Discord Developer Portal, generate an install URL and invite the bot to the right server.
322
+ 11. Send a test message in Discord and confirm the brain responds.
323
+
324
+ Notes:
39
325
 
40
- 1. bump `@rizom/ops` in `package.json`
41
- 2. rerun the relevant scaffold/reconcile flow
42
- 3. review the resulting changes to `.env.schema`, `deploy/scripts/`, and workflows in git
43
- 4. commit the updated deploy artifacts together
326
+ - Use **one Discord application credential set per user/brain**.
327
+ - Do not reuse the same Discord application across multiple pilot users.
328
+ - Discord is the default pilot interface moving forward.
329
+ - The encrypted `users/<handle>.secrets.yaml.age` file is the durable checked-in deploy input; your local env is only the operator staging source.
330
+ - Direct MCP client access should use OAuth/passkey-capable clients where possible.
331
+ - When explaining the content workflow, describe it first as a normal **git repo** of **markdown/text files**.
332
+ - Position **Obsidian** as optional: it is just one possible editor for those same files, not the default requirement.
44
333
 
45
334
  ## Recovery notes
46
335
 
@@ -0,0 +1,90 @@
1
+ # Welcome to your brain
2
+
3
+ ---
4
+
5
+ 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.
6
+
7
+ 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.
8
+
9
+ ---
10
+
11
+ ## What it is
12
+
13
+ Your brain is a private knowledge companion. It holds your notes, links, and ideas and helps you think with them, not just store them.
14
+
15
+ Ask a question and it searches what you've saved. Give it a fragment of thinking and it can help develop it.
16
+
17
+ ## Getting in
18
+
19
+ We'll send you a personal URL such as `https://<handle>.rizom.ai/`.
20
+
21
+ The first time you open it, you will be asked to set a passkey. No password is required after that.
22
+
23
+ Your main interfaces are:
24
+
25
+ - **Chat** (`/chat`) — talk to your brain;
26
+ - **Dashboard/site** (`/`) — the configured browser surface;
27
+ - **CMS** (`/cms`) — edit durable content in a browser.
28
+
29
+ Start with Chat.
30
+
31
+ ## Your first five minutes
32
+
33
+ 1. Open Chat and say: _Help me save my first note._
34
+ 2. Save a thought, link, or idea. It does not need to be polished.
35
+ 3. Ask about it and inspect what comes back.
36
+
37
+ That save–ask–use loop is the core workflow.
38
+
39
+ ## Chat or CMS?
40
+
41
+ **Chat** is for thinking aloud, asking questions, saving things quickly, and day-to-day work.
42
+
43
+ **CMS** is for deliberate browsing and editing. It becomes more useful as your content grows.
44
+
45
+ ## Other interfaces and peer brains
46
+
47
+ 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.
48
+
49
+ With permission, you can save another participant's brain as a contact and call it by its shared address:
50
+
51
+ - _Add jane.rizom.ai to my contacts._
52
+ - _Call jane.rizom.ai and ask [your question]._
53
+
54
+ ## Connecting other tools
55
+
56
+ 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.
57
+
58
+ ## Common questions
59
+
60
+ **How do I access my data?**
61
+
62
+ Use the CMS. If your cohort includes GitHub access, the same durable markdown also lives in a private repository.
63
+
64
+ **Does it search the public internet?**
65
+
66
+ Not by default. Answers are grounded in your own knowledge unless an explicitly configured integration provides another source.
67
+
68
+ **What does this cost?**
69
+
70
+ Nothing during the pilot; hosting is covered by the programme.
71
+
72
+ ## This is a pilot
73
+
74
+ 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.
75
+
76
+ A built-in wishlist can record unsupported requests as product feedback.
77
+
78
+ ## Your access details
79
+
80
+ We will send details in this shape:
81
+
82
+ ```text
83
+ Chat URL: https://<handle>.rizom.ai/chat
84
+ Dashboard URL: https://<handle>.rizom.ai/
85
+ CMS URL: https://<handle>.rizom.ai/cms
86
+ Discord: yes/no — setup steps if enabled
87
+ MCP: enabled/not enabled — setup details if enabled
88
+ ```
89
+
90
+ If anything is unclear, reply with what you see and we will help.
@@ -3,6 +3,9 @@
3
3
  "private": true,
4
4
  "type": "module",
5
5
  "packageManager": "bun@__BUN_VERSION__",
6
+ "dependencies": {
7
+ "age-encryption": "^0.3.0"
8
+ },
6
9
  "devDependencies": {
7
10
  "@rizom/ops": "__BRAINS_OPS_VERSION__"
8
11
  }
@@ -1,8 +1,10 @@
1
- schemaVersion: 1
2
1
  brainVersion: 0.1.1-alpha.14
3
- model: rover
4
2
  githubOrg: <github-org>
5
3
  contentRepoPrefix: rover-
6
4
  domainSuffix: .rizom.ai
7
- preset: core
5
+ bundles:
6
+ - core
8
7
  aiApiKey: AI_API_KEY
8
+ gitSyncToken: GIT_SYNC_TOKEN
9
+ contentRepoAdminToken: CONTENT_REPO_ADMIN_TOKEN
10
+ agePublicKey: age1replace-with-your-public-key
@@ -1,3 +1,7 @@
1
1
  handle: alice
2
+ anchorProfile:
3
+ name: Alice Example
4
+ description: Replace this with Alice's real public profile summary.
2
5
  discord:
3
- enabled: false
6
+ enabled: true
7
+ # anchorUserId: "123456789012345678"
@@ -1,6 +0,0 @@
1
- export interface UserSecretNames {
2
- gitSyncTokenSecretName: string;
3
- mcpAuthTokenSecretName: string;
4
- discordBotTokenSecretName: string;
5
- }
6
- export declare function deriveUserSecretNames(handle: string): UserSecretNames;
@@ -1,9 +0,0 @@
1
- #!/usr/bin/env bash
2
- set -euo pipefail
3
-
4
- BRAIN_FILE="${BRAIN_YAML_PATH:-brain.yaml}"
5
- SSH_USER="$(ruby -e 'require "yaml"; config = YAML.load_file("deploy/kamal/deploy.yml") || {}; puts(config.dig("ssh", "user") || "root")')"
6
- IFS=',' read -ra HOSTS <<< "$KAMAL_HOSTS"
7
- for host in "${HOSTS[@]}"; do
8
- scp -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null "$BRAIN_FILE" "${SSH_USER}@${host}:/opt/brain.yaml"
9
- done
@@ -1,15 +0,0 @@
1
- ARG BUN_VERSION=1.3.10
2
- FROM oven/bun:${BUN_VERSION}-slim
3
-
4
- ARG BRAIN_VERSION
5
- WORKDIR /app
6
-
7
- RUN test -n "$BRAIN_VERSION" \
8
- && printf '{"name":"rover-pilot-runtime","private":true}\n' > package.json \
9
- && bun add @rizom/brain@$BRAIN_VERSION
10
-
11
- ENV XDG_DATA_HOME=/data
12
- ENV XDG_CONFIG_HOME=/config
13
- RUN mkdir -p /app/brain-data /data /config && chmod -R 777 /app/brain-data /data /config
14
-
15
- CMD ["sh", "-c", "exec ./node_modules/.bin/brain start"]
@@ -1,39 +0,0 @@
1
- service: rover
2
- image: <%= ENV['IMAGE_REPOSITORY'] %>
3
-
4
- servers:
5
- mcp:
6
- hosts:
7
- - <%= ENV['SERVER_IP'] %>
8
-
9
- proxy:
10
- ssl:
11
- certificate_pem: CERTIFICATE_PEM
12
- private_key_pem: PRIVATE_KEY_PEM
13
- hosts:
14
- - <%= ENV['BRAIN_DOMAIN'] %>
15
- app_port: 3333
16
- healthcheck:
17
- path: /health
18
-
19
- registry:
20
- server: ghcr.io
21
- username: <%= ENV['REGISTRY_USERNAME'] %>
22
- password:
23
- - KAMAL_REGISTRY_PASSWORD
24
-
25
- builder:
26
- arch: amd64
27
-
28
- env:
29
- clear:
30
- NODE_ENV: production
31
- secret:
32
- - AI_API_KEY
33
- - GIT_SYNC_TOKEN
34
- - MCP_AUTH_TOKEN
35
- - DISCORD_BOT_TOKEN
36
-
37
- volumes:
38
- - /opt/brain-data:/app/brain-data
39
- - /opt/brain.yaml:/app/brain.yaml