@rizom/ops 0.2.0-alpha.119 → 0.2.0-alpha.120

package/dist/index.js

@@ -53,7 +53,7 @@ return `+str.trim()+`;
 `).join(`
 `+Y),$.push(Q+"m+"+SY.exports.humanize(this.diff)+"\x1B[0m")}else $[0]=bA()+q+" "+$[0]}function bA(){if(nM.inspectOpts.hideDate)return"";return new Date().toISOString()+" "}function kA(...$){return process.stderr.write(TY.formatWithOptions(nM.inspectOpts,...$)+`
 `)}function mA($){if($)process.env.DEBUG=$;else delete process.env.DEBUG}function yA(){return process.env.DEBUG}function fA($){$.inspectOpts={};let q=Object.keys(nM.inspectOpts);for(let J=0;J<q.length;J++)$.inspectOpts[q[J]]=nM.inspectOpts[q[J]]}SY.exports=bX()(nM);var{formatters:cM}=SY.exports;cM.o=function($){return this.inspectOpts.colors=this.useColors,TY.inspect($,this.inspectOpts).split(`
-`).map((q)=>q.trim()).join(" ")};cM.O=function($){return this.inspectOpts.colors=this.useColors,TY.inspect($,this.inspectOpts)}});var sM=X$((cv,yX)=>{if(typeof process>"u"||process.type==="renderer"||!1||process.__nwjs)yX.exports=uM();else yX.exports=aM()});var oz=X$((Ay,nz)=>{var bY=Object.prototype.hasOwnProperty,cz=Object.prototype.toString,uz=Object.defineProperty,pz=Object.getOwnPropertyDescriptor,lz=function(q){if(typeof Array.isArray==="function")return Array.isArray(q);return cz.call(q)==="[object Array]"},rz=function(q){if(!q||cz.call(q)!=="[object Object]")return!1;var J=bY.call(q,"constructor"),G=q.constructor&&q.constructor.prototype&&bY.call(q.constructor.prototype,"isPrototypeOf");if(q.constructor&&!J&&!G)return!1;var Q;for(Q in q);return typeof Q>"u"||bY.call(q,Q)},iz=function(q,J){if(uz&&J.name==="__proto__")uz(q,J.name,{enumerable:!0,configurable:!0,value:J.newValue,writable:!0});else q[J.name]=J.newValue},dz=function(q,J){if(J==="__proto__"){if(!bY.call(q,J))return;else if(pz)return pz(q,J).value}return q[J]};nz.exports=function $(){var q,J,G,Q,Y,X,U=arguments[0],W=1,V=arguments.length,M=!1;if(typeof U==="boolean")M=U,U=arguments[1]||{},W=2;if(U==null||typeof U!=="object"&&typeof U!=="function")U={};for(;W<V;++W)if(q=arguments[W],q!=null){for(J in q)if(G=dz(U,J),Q=dz(q,J),U!==Q){if(M&&Q&&(rz(Q)||(Y=lz(Q)))){if(Y)Y=!1,X=G&&lz(G)?G:[];else X=G&&rz(G)?G:{};iz(U,{name:J,newValue:$(M,X,Q)})}else if(typeof Q<"u")iz(U,{name:J,newValue:Q})}}return U}});import{access as vI,chmod as _U,mkdir as DD,readFile as HD,writeFile as KD}from"fs/promises";import{dirname as bI,join as bU}from"path";import{fileURLToPath as kI}from"url";var sQ={name:"@rizom/ops",description:"Operator CLI for managing private brain fleet registry repos",publishConfig:{access:"public"},version:"0.2.0-alpha.119",type:"module",exports:{".":{types:"./dist/index.d.ts",import:"./dist/index.js"},"./deploy":{bun:"./dist/deploy.js",types:"./dist/deploy.d.ts",import:"./dist/deploy.js"}},main:"./dist/index.js",types:"./dist/index.d.ts",bin:{"brains-ops":"./dist/brains-ops.js"},files:["dist","templates"],scripts:{build:"bun scripts/build.ts",prepublishOnly:"bun scripts/build.ts",typecheck:"tsc --noEmit",lint:"eslint . --ext .ts","lint:fix":"eslint . --ext .ts --fix",test:"bun run build && bun test --timeout 20000","test:smoke":"bun run build && RUN_SMOKE_TESTS=1 bun test --timeout 60000"},dependencies:{"age-encryption":"^0.3.0"},devDependencies:{"@brains/deploy-support":"workspace:*","@brains/eslint-config":"workspace:*","@brains/typescript-config":"workspace:*","@brains/utils":"workspace:*","@types/bun":"latest",typescript:"^5.3.3"},repository:{type:"git",url:"https://github.com/rizom-ai/brains.git",directory:"packages/brains-ops"},license:"Apache-2.0",author:"Yeehaa <yeehaa@rizom.ai> (https://rizom.ai)",homepage:"https://github.com/rizom-ai/brains/tree/main/packages/brains-ops#readme",bugs:"https://github.com/rizom-ai/brains/issues",engines:{bun:">=1.3.3"},keywords:["brains","ops","cli","deploy","fleet","operator"]};var r7=`ARG BUN_VERSION=1.3.10
+`).map((q)=>q.trim()).join(" ")};cM.O=function($){return this.inspectOpts.colors=this.useColors,TY.inspect($,this.inspectOpts)}});var sM=X$((cv,yX)=>{if(typeof process>"u"||process.type==="renderer"||!1||process.__nwjs)yX.exports=uM();else yX.exports=aM()});var oz=X$((Ay,nz)=>{var bY=Object.prototype.hasOwnProperty,cz=Object.prototype.toString,uz=Object.defineProperty,pz=Object.getOwnPropertyDescriptor,lz=function(q){if(typeof Array.isArray==="function")return Array.isArray(q);return cz.call(q)==="[object Array]"},rz=function(q){if(!q||cz.call(q)!=="[object Object]")return!1;var J=bY.call(q,"constructor"),G=q.constructor&&q.constructor.prototype&&bY.call(q.constructor.prototype,"isPrototypeOf");if(q.constructor&&!J&&!G)return!1;var Q;for(Q in q);return typeof Q>"u"||bY.call(q,Q)},iz=function(q,J){if(uz&&J.name==="__proto__")uz(q,J.name,{enumerable:!0,configurable:!0,value:J.newValue,writable:!0});else q[J.name]=J.newValue},dz=function(q,J){if(J==="__proto__"){if(!bY.call(q,J))return;else if(pz)return pz(q,J).value}return q[J]};nz.exports=function $(){var q,J,G,Q,Y,X,U=arguments[0],W=1,V=arguments.length,M=!1;if(typeof U==="boolean")M=U,U=arguments[1]||{},W=2;if(U==null||typeof U!=="object"&&typeof U!=="function")U={};for(;W<V;++W)if(q=arguments[W],q!=null){for(J in q)if(G=dz(U,J),Q=dz(q,J),U!==Q){if(M&&Q&&(rz(Q)||(Y=lz(Q)))){if(Y)Y=!1,X=G&&lz(G)?G:[];else X=G&&rz(G)?G:{};iz(U,{name:J,newValue:$(M,X,Q)})}else if(typeof Q<"u")iz(U,{name:J,newValue:Q})}}return U}});import{access as vI,chmod as _U,mkdir as DD,readFile as HD,writeFile as KD}from"fs/promises";import{dirname as bI,join as bU}from"path";import{fileURLToPath as kI}from"url";var sQ={name:"@rizom/ops",description:"Operator CLI for managing private brain fleet registry repos",publishConfig:{access:"public"},version:"0.2.0-alpha.120",type:"module",exports:{".":{types:"./dist/index.d.ts",import:"./dist/index.js"},"./deploy":{bun:"./dist/deploy.js",types:"./dist/deploy.d.ts",import:"./dist/deploy.js"}},main:"./dist/index.js",types:"./dist/index.d.ts",bin:{"brains-ops":"./dist/brains-ops.js"},files:["dist","templates"],scripts:{build:"bun scripts/build.ts",prepublishOnly:"bun scripts/build.ts",typecheck:"tsc --noEmit",lint:"eslint . --ext .ts","lint:fix":"eslint . --ext .ts --fix",test:"bun run build && bun test --timeout 20000","test:smoke":"bun run build && RUN_SMOKE_TESTS=1 bun test --timeout 60000"},dependencies:{"age-encryption":"^0.3.0"},devDependencies:{"@brains/deploy-support":"workspace:*","@brains/eslint-config":"workspace:*","@brains/typescript-config":"workspace:*","@brains/utils":"workspace:*","@types/bun":"latest",typescript:"^5.3.3"},repository:{type:"git",url:"https://github.com/rizom-ai/brains.git",directory:"packages/brains-ops"},license:"Apache-2.0",author:"Yeehaa <yeehaa@rizom.ai> (https://rizom.ai)",homepage:"https://github.com/rizom-ai/brains/tree/main/packages/brains-ops#readme",bugs:"https://github.com/rizom-ai/brains/issues",engines:{bun:">=1.3.3"},keywords:["brains","ops","cli","deploy","fleet","operator"]};var r7=`ARG BUN_VERSION=1.3.10
 FROM oven/bun:\${BUN_VERSION}-slim AS runtime
 
 WORKDIR /app
@@ -269,7 +269,7 @@ volumes:
 .brains-ops/
 users/*.secrets.yaml
 `;if($==="deploy/Dockerfile")return n7();if($==="deploy/kamal/deploy.yml")return tQ({serviceName:"rover"});if($===".kamal/hooks/pre-deploy")return a9({deployConfigPath:"deploy/kamal/deploy.yml",brainYamlPath:"${BRAIN_YAML_PATH:-brain.yaml}"});let q=bU(yI,$),J=await HD(q,"utf8");return cI(J)}function cI($){return $.replaceAll("__BRAINS_OPS_VERSION__",sQ.version).replaceAll("__BUN_VERSION__",Bun.version)}function nI($,q){return typeof $==="object"&&$!==null&&"code"in $&&$.code===q}import{mkdir as H2,writeFile as O2}from"fs/promises";import{dirname as N2,join as ZD}from"path";import{mkdtemp as aI,mkdir as sI,readFile as tI,rm as eI,writeFile as $2}from"fs/promises";import{tmpdir as q2}from"os";import{dirname as J2,join as wD}from"path";import{spawn as oI}from"child_process";var b0=async($,q,J={})=>new Promise((G,Q)=>{let Y=oI($,q,{stdio:["pipe","inherit","inherit"],env:J.env?{...process.env,...J.env}:process.env,cwd:J.cwd});if(Y.on("error",Q),Y.on("close",(X)=>{if(X===0){G();return}Q(Error(`${$} ${q.join(" ")} exited with code ${X??1}`))}),J.stdin)Y.stdin.end(J.stdin);else Y.stdin.end()});var G2=["name: Your Name Here","Delete this and write your own"];async function jD($,q,J,G,Q={}){if(G.length===0)return;let Y=Q.env??process.env,X=u0($),U=OD(Y,X,J.effectiveGitSyncToken),W=Q.contentRepoAdminTokenSelector?OD(Y,X,Q.contentRepoAdminTokenSelector):void 0,V=Q.contentRepoRemoteResolver?.(J,q,U)??X2(q,J.contentRepo,U);if(!V)return;let M=await aI(wD(q2(),`brains-ops-content-sync-${J.handle}-`)),z=Q.runCommand??b0,D=Q.fetchImpl??fetch;try{if(!Q.contentRepoRemoteResolver){if(!W)throw Error(`${Q.contentRepoAdminTokenSelector??"CONTENT_REPO_ADMIN_TOKEN"} is required to check or create content repos`);await U2(q,J.contentRepo,W,D)}await z("git",["clone",V,M]),await W2(M,z),await z("git",["config","user.name","brains-ops[bot]"],{cwd:M}),await z("git",["config","user.email","41898282+github-actions[bot]@users.noreply.github.com"],{cwd:M});let R=!1;for(let N of G)if(await Q2(M,N))R=!0;if(!R)return;await z("git",["add","."],{cwd:M}),await z("git",["commit","-m",`chore(content): seed ${J.handle} anchor profile`],{cwd:M}),await z("git",["push","origin","HEAD:main"],{cwd:M})}finally{await eI(M,{recursive:!0,force:!0})}}async function Q2($,q){let J=wD($,q.path),G=await tI(J,"utf8").catch(()=>{return});if(G===q.content)return!1;if(G!==void 0&&!Y2(G))return!1;return await sI(J2(J),{recursive:!0}),await $2(J,q.content),!0}function Y2($){return G2.some((q)=>$.includes(q))}function OD($,q,J){return f$(J,$,q)}function X2($,q,J){if(!J)return;return`https://x-access-token:${encodeURIComponent(J)}@github.com/${$}/${q}.git`}async function U2($,q,J,G){let Y=`https://api.github.com/repos/${`${encodeURIComponent($)}/${encodeURIComponent(q)}`}`,X={Accept:"application/vnd.github+json",Authorization:`Bearer ${J}`,"User-Agent":"brains-ops","X-GitHub-Api-Version":"2022-11-28"},U=await G(Y,{headers:X});if(U.ok)return;if(U.status!==404)throw Error(`Failed to check GitHub repo ${$}/${q}: ${U.status} ${await ND(U)}`);let W=await G(`https://api.github.com/orgs/${encodeURIComponent($)}/repos`,{method:"POST",headers:X,body:JSON.stringify({name:q,private:!0,auto_init:!1})});if(W.ok){console.log(`Created missing content repo ${$}/${q}`);return}if(W.status===422){if((await G(Y,{headers:X})).ok)return}throw Error(`Failed to create GitHub repo ${$}/${q}: ${W.status} ${await ND(W)}`)}async function ND($){let q=await $.text();return q.trim().length===0?$.statusText:q}async function W2($,q){try{await q("git",["checkout","-B","main","origin/main"],{cwd:$})}catch{await q("git",["checkout","-B","main"],{cwd:$})}}function AD($){return async(q)=>({brainYaml:V2(q,$),envFile:K2(q,$),contentRepoFiles:R2(q)})}function V2($,q){let J=[`brain: ${$.model}`,`domain: ${$.domain}`,`preset: ${$.preset}`,"",z2($),"","plugins:",...$.setup?.delivery==="email"?["  auth-service:",...M2($.setup.email)]:[],"  directory-sync:","    git:",`      repo: ${q}/${$.contentRepo}`,"      authToken: ${GIT_SYNC_TOKEN}",...$.atproto?["  atproto:",`    identifier: ${$.atproto.identifier}`,"    appPassword: ${ATPROTO_APP_PASSWORD}"]:[]];if($.discordEnabled)J.push("  discord:"),J.push("    botToken: ${DISCORD_BOT_TOKEN}");if($.setup?.delivery==="email")J.push("  email-resend:"),J.push("    apiKey: ${SETUP_EMAIL_API_KEY}"),J.push("    from: ${SETUP_EMAIL_FROM}");return J.push(""),J.join(`
-`)}function M2($){return["    setupEmail:",`      to: ${$}`,"      subject: Welcome to Rover \u2014 set up your passkey","      body: |","        Hi,","","        Your Rover is ready.","","        Rover is your private AI assistant for working with your own notes, links, and ideas.","","        Set up your passkey:","        {{setupUrl}}","","        This link is single-use. Do not forward it.","        It expires at {{expiresAt}}.","","        After setup:","        - Open your dashboard: {{origin}}/","        - If Discord is enabled for your pilot, start there.","        - If you are testing MCP, connect your client to {{origin}}/mcp and use OAuth/browser login with your passkey.","","        Read the Rover Pilot User Onboarding guide for Discord, content repo, CMS, and client-specific MCP details:","        https://github.com/rizom-ai/brains/blob/main/packages/brains-ops/templates/rover-pilot/docs/user-onboarding.md","","        If this link is expired, does not work, or you did not expect this email, reply to your Rover operator and we will help."]}function z2($){if($.discordEnabled&&$.discordAnchorUserId)return`anchors: ["discord:${$.discordAnchorUserId}"]`;return"anchors: []"}function R2($){return[{path:"anchor-profile/anchor-profile.md",content:D2($)}]}function D2($){let q={kind:"professional",name:$.anchorProfile.name,...$.anchorProfile.description?{description:$.anchorProfile.description}:{},...$.anchorProfile.website?{website:$.anchorProfile.website}:{},...$.anchorProfile.email?{email:$.anchorProfile.email}:{},...$.anchorProfile.socialLinks?{socialLinks:$.anchorProfile.socialLinks}:{}},J=$.anchorProfile.story??"This profile was initialized by brains-ops. Edit it in your content repo.";return`---
+`)}function M2($){return["    setupEmail:",`      to: ${$}`,"      subject: Welcome to Rover \u2014 set up your passkey","      body: |","        Hi,","","        Your Rover is ready.","","        Rover is your own AI \u2014 a private assistant deployed just for you, that holds your notes, links, and ideas, and gets more useful the more you put into it.","","        Set up your passkey:","        {{setupUrl}}","","        This link is single-use. Do not forward it.","        It expires at {{expiresAt}}.","","        After setup, open your chat and say hello:","        {{origin}}/chat","","        Sign in with the passkey you just registered. The chat in your browser is where you and Rover will spend most of your time.","","        The onboarding guide shows the way of working \u2014 capture, ask back, shape:","        https://github.com/rizom-ai/brains/blob/main/packages/brains-ops/templates/rover-pilot/docs/user-onboarding.md","","        If this link is expired, does not work, or you did not expect this email, reply to your Rover operator and we will help."]}function z2($){if($.discordEnabled&&$.discordAnchorUserId)return`anchors: ["discord:${$.discordAnchorUserId}"]`;return"anchors: []"}function R2($){return[{path:"anchor-profile/anchor-profile.md",content:D2($)}]}function D2($){let q={kind:"professional",name:$.anchorProfile.name,...$.anchorProfile.description?{description:$.anchorProfile.description}:{},...$.anchorProfile.website?{website:$.anchorProfile.website}:{},...$.anchorProfile.email?{email:$.anchorProfile.email}:{},...$.anchorProfile.socialLinks?{socialLinks:$.anchorProfile.socialLinks}:{}},J=$.anchorProfile.story??"This profile was initialized by brains-ops. Edit it in your content repo.";return`---
 ${qQ(q).trimEnd()}
 ---
 

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.0-alpha.119",
+  "version": "0.2.0-alpha.120",
   "type": "module",
   "exports": {
     ".": {

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

@@ -8,11 +8,12 @@
    - 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>`.
+   - Web chat is the primary interface; it needs no per-user setup beyond the passkey.
+   - `user:add` currently writes `discord: enabled: true`; set it to `false` unless the user's cohort actually uses Discord.
+   - if the user should be an anchor on Discord, 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.
+   - Set `setup.delivery: email` and `setup.email` so the user gets the passkey setup email — this is the default onboarding path.
    - For ATProto publishing, add `atproto.identifier` to the user file; put only `atprotoAppPassword` in the per-user secrets 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>`.
@@ -25,20 +26,21 @@
 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:
-      - `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:
+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`
     - 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.
+    - CMS: `https://<handle>.rizom.ai/cms`, plus GitHub token guidance if CMS editing is part of their cohort
+17. For Discord-enabled cohorts, hand the Discord setup details to the user as a secondary chat surface.
+18. If they need direct client access (MCP), use OAuth/passkey-capable clients where possible.
+19. 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.
+20. Send `docs/user-onboarding.md` to the user as the pilot handoff guide.

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

@@ -1,339 +1,217 @@
-# Rover Pilot User Onboarding
+# Welcome to Rover
 
-Welcome to the Rover pilot.
+Rover is your own AI. Not a chatbot you share with the rest of the
+world — a private assistant deployed just for you, that holds your
+notes, links, and ideas, and gets more useful the more you put into
+it.
 
-This guide is for first-time Rover users. You do not need prior experience with Rover, MCP, git, GitHub, or Obsidian to get started.
+This guide walks you through your first days. You don't need
+experience with any particular tools — if you can use a browser, you
+can use Rover.
 
-## What Rover is
+## Get in and say hello
 
-Rover is your private AI assistant for working with your own notes, links, and ideas.
+1. **Open the setup email** we sent you and click the setup link.
+2. **Register a passkey** — your browser will offer fingerprint,
+   face, or PIN. This becomes how you sign in; there is no password.
+3. **Open your chat**: `https://<handle>.rizom.ai/chat` — sign in
+   with the passkey you just made.
+4. **Say hello.** Ask Rover:
 
-For the current pilot, the normal core experience is:
+   > What can you help me do?
 
-- **Passkey setup email** — your secure first step
-- **Discord** — the main chat interface when enabled for your pilot
-- **Dashboard** — your browser overview at `https://<handle>.rizom.ai/`
-- **MCP** — optional direct access from OAuth/passkey-capable AI clients
+That's the whole setup. The chat in your browser is where you and
+Rover will spend most of your time.
 
-Some users may also receive:
+One caution: the setup link works once and then expires. Don't
+forward it, and if it has already expired when you click it, just
+tell us — we'll send a fresh one.
 
-- **CMS** access at `https://<handle>.rizom.ai/cms`
-- **GitHub/content repo** access for editing the underlying markdown files
-- **Obsidian** instructions for a local file-based workflow
+## What your Rover holds
 
-If we did not explicitly give you CMS, GitHub, MCP, or Obsidian instructions, you can ignore those sections for now.
+Everything in Rover is one of a few simple kinds of things:
 
-## Start here: setup
+- **Notes** — thoughts, ideas, observations in your own words.
+- **Links** — things from the web, saved with why they matter to you.
+- **Documents** — files you drop into chat: Markdown, PDFs, images.
+- **Topics** — the themes running through your material. You don't
+  create these; Rover notices them.
+- **Wishes** — things you asked for that Rover can't do yet.
+- **Agents** — other people's brains, saved to your directory so you
+  can ask them things.
 
-1. Open the setup email from Rover.
-2. Click the passkey setup link.
-3. Register a passkey in your browser.
-4. Open your Dashboard: `https://<handle>.rizom.ai/`.
-5. If Discord is enabled for you, send Rover a first message there.
-6. If we asked you to test MCP, use the separate MCP connection instructions we sent for your pilot.
+You'll meet each of these as you go. The first three you put in; the
+last three grow out of how you use it.
 
-## Your setup email
+## The way of working
 
-The setup email contains a single-use passkey setup link.
+Rover is built around a simple loop:
 
-Treat that link like a temporary password:
+**Capture → ask back → shape.**
 
-- do not forward it
-- use it once
-- expect it to expire
-- ask us for help if it has expired or does not work
+What makes it work: every note, link, and document you hand Rover
+lands in one connected memory. Rover reads what you save, links it
+to what's already there, and notices the topics running through it.
+Nothing sits in a folder waiting to be found — every capture makes
+the next answer better. Ten notes in, Rover is a notebook; a hundred
+notes in, it starts knowing how you think.
 
-After you register your passkey, the setup link closes. Your passkey becomes the sign-in method for Rover's browser and OAuth-capable client flows.
+The important part is what you _don't_ do: you don't organize. No
+folders, no tags, no filing things in the right place. You throw
+material in as it comes, and Rover makes sense of it when you need
+it.
 
-If your Rover already existed before you received this email, nothing is being reset. The email is just the secure handoff for registering your own passkey so you can sign in yourself.
+### Capture
 
-## Your first Rover session
+Notes for what's in your head:
 
-Start in **Discord** if it is enabled for your pilot. That is the normal first interface.
+> Save a note: I keep explaining the same idea to clients — maybe
+> it should be a workshop.
 
-### 1. Say hello
+Links for what's on your screen:
 
-Send:
+> Save this link with my workshop idea — it's how someone else
+> structures theirs: https://example.com
 
-> What can you help me do, and what should I use you for?
+Documents for what you already have: drop a Markdown file, a PDF, or
+an image into the chat and ask Rover to save or import it. If you
+have notes living somewhere else, this is the fastest way to give
+Rover a head start.
 
-Rover should answer with a short overview of what it can do.
+### Ask back
 
-### 2. Create your first note
+Ask in whatever words occur to you — Rover searches by meaning, not
+exact phrases, so you don't have to remember what you called
+something:
 
-Ask Rover to save a simple note:
+> What have I added about the workshop idea?
 
-> Save a note: I am trying Rover because I want a better way to collect ideas, links, and questions in one place.
+> What did I save this week?
 
-Or:
+And as material accumulates, the topics surface — the themes you
+keep returning to without noticing:
 
-> Help me save my first note.
+> What themes do you see in what I've collected?
 
-### 3. Add your first link
+### Shape
 
-Send Rover a link you want to remember:
+When you want to make something from what you've gathered:
 
-> Save this link and tell me why it might be useful later: https://example.com
+> Turn my workshop notes into a one-page outline.
 
-Or:
+> Make a reading list from the links I saved.
 
-> Add this as a link about tools I want to revisit: https://example.com
+Capture is cheap, asking back is instant, and shaping turns a pile
+of fragments into something you can use. That loop is Rover — and it
+only proves itself on real material, so start with things you
+actually want to keep.
 
-Rover should save the link and, when possible, keep a short description of why it matters.
+## When Rover can't do something: make a wish
 
-### 4. Upload an existing Markdown doc
+Sooner or later you'll ask for something Rover can't do yet. That's
+where wishes come from: Rover says so honestly and offers to save
+the request as a wish:
 
-If you already have notes or docs in Markdown, you do not need to retype them.
+> I wish you could remind me about this next Monday.
 
-Upload a `.md` file and ask Rover to save or import it:
+Wishes flow back to us and shape what gets built next. Asking for
+things Rover can't do is not a failure — it's one of the most useful
+things a pilot user can do.
 
-> Save this Markdown doc in my notes.
+## Your Rover in the network
 
-Or:
+The loop has a second payoff. Rover isn't only a private assistant —
+it's your agent in a network of brains, and the connection runs both
+ways.
 
-> Import this doc and tell me what it is about.
+**Other people's brains become sources.** When someone you know runs
+a brain, you don't have to send them a message and wait — you ask
+their brain directly, from your own chat. Save it to your agents
+once:
 
-This is often the fastest way to give Rover useful context.
+> Add yeehaa.io to my agents.
 
-### 5. Ask Rover about what you just added
+Then ask questions that put their knowledge next to yours:
 
-After you have saved a note, link, or Markdown doc, ask Rover to reflect it back:
+> Ask yeehaa.io what they've published about designing workshops,
+> and compare it with my own workshop notes.
 
-> What have I added so far?
+One ask, both directions: Rover pulls their public knowledge over
+the network, sets it against the material you've been capturing, and
+answers in terms of your situation. What comes back you can think
+with, push back on, or capture:
 
-Or:
+> Save that comparison as a note with my workshop idea.
 
-> What do you know about what I am interested in so far?
+That's the loop again, with someone else's knowledge feeding your
+capture. Rover never contacts an agent you haven't saved without
+telling you first, and your private material is never shared — only
+the question you send.
 
-This is the basic Rover loop: add material, then ask Rover to help you think with it.
+**Your brain becomes a source for others.** The same way you ask
+other agents, they can ask yours. Your Rover answers on your behalf,
+drawing only on what you've chosen to make public — and it builds
+its picture of what you know from everything you capture.
 
-### 6. Try a more useful task
+So the network is the quiet consequence of the loop: the more you
+put in, the more useful your Rover is to you — and the better it
+speaks for you when you're not in the room.
 
-Once Rover has a little context, try one of these:
+## The other doors
 
-> Summarize my notes so far.
+Chat is the primary interface, but your Rover has a few more
+entrances. All optional — ignore them until you're curious:
 
-> What themes do you see in what I have added?
+- **Dashboard** — `https://<handle>.rizom.ai/` is your Rover's home
+  page in the browser: a quick overview that everything is running.
+- **CMS** — `https://<handle>.rizom.ai/cms` is a browser editor for
+  your content, useful when you want to write or restructure
+  something longer than a chat message. If it asks for GitHub
+  access, use the instructions we sent; if we didn't send any, skip
+  the CMS for now.
+- **Your own AI client (MCP)** — Rover can plug into AI apps you
+  already use (Claude, Cursor, and others), signed in with the same
+  passkey. If you want this, ask us and we'll send the short setup.
+- **Discord** — available for some pilot cohorts as a secondary
+  chat. If it's enabled for you, we'll send the invite separately.
 
-> Turn my rough note into a clearer paragraph.
+Under the hood, everything you save is plain Markdown in a private
+repository that belongs to you. You never have to touch it — but
+your material is never locked in, either.
 
-> Help me make a small reading list from the links I saved.
+## What to expect from the pilot
 
-These examples show the main scope of Rover: saving material, organizing it, reflecting on it, and helping you make something from it.
+This is a real, working system, and an early one. Expect occasional
+rough edges and visible improvement while you use it. Your Rover is
+deployed specifically for you, your content lives in your own
+private store, and sign-in is by passkey. One ask: avoid putting
+highly sensitive material in during the pilot unless we've agreed
+it's in scope — when unsure, ask.
 
-### 7. Ask another agent
+For questions, feedback, or anything that feels off, join our
+Discord server: `<discord-invite>`. That's the fastest way to reach
+us, and you'll meet the other pilot users there too.
 
-If your pilot has agent-to-agent access enabled, we will tell you which other agents you can address and how to talk to them. Otherwise Rover should clearly say that this workflow is not available yet.
+## If something doesn't work
 
-## The default mental model
+- **No setup email** — check spam first, then tell us which address
+  to use.
+- **Setup link expired** — tell us; we'll reissue it.
+- **Browser asks for a passkey** — expected; use the one you
+  registered during setup.
+- **Anything else** — post in the Discord server with the exact
+  error text or a screenshot and we'll sort it out. Never paste your
+  setup link anywhere except your own browser.
 
-If you remember only one thing, remember this:
+## Tell us what you notice
 
-- **Discord** = talk to Rover, when enabled
-- **Dashboard** = browser overview
-- **MCP** = optional direct client integration through OAuth/passkey login
-- **CMS / git / Obsidian** = optional content-editing workflows when we enable them for you
+The feedback that helps most is small and honest — drop it in the
+Discord server as it occurs to you:
 
-## What you will receive from us
+- where setup confused you
+- what felt useful right away, and what felt pointless
+- what you expected Rover to do that it couldn't
+- whether the capture → ask back → shape loop fits how you work
+- whether you'd keep using Rover after the pilot
 
-Depending on your pilot cohort, we will send you some or all of these:
-
-- a passkey setup email from Rover
-- this onboarding guide, or a link to it
-- confirmation that Discord is enabled for you, plus the invite/setup steps
-- your **Dashboard URL**: `https://<handle>.rizom.ai/`
-- CMS URL and GitHub token instructions, if CMS editing is enabled
-- private content repo access, if file-based editing is enabled
-- separate MCP connection instructions, if MCP testing is enabled
-- any extra instructions if we are testing a specific workflow with your cohort
-
-Keep setup links, GitHub tokens, and any MCP credentials separate. Do not paste the passkey setup link into an MCP client.
-
-## Discord
-
-Discord is the default chat interface when it is enabled for your pilot. It is separate from the passkey setup email: the email sets up browser/client identity, while Discord is where many users chat with Rover day to day.
-
-Use it to:
-
-- save quick notes
-- drop in links
-- ask questions
-- use Rover day to day without setting up a separate client
-
-If Discord is enabled, we will send the exact invite/setup steps separately.
-
-## Dashboard basics
-
-The Dashboard is the browser landing page for your Rover.
-
-Open it at:
-
-```text
-https://<handle>.rizom.ai/
-```
-
-Use it to confirm your Rover is up, see available endpoints, and orient yourself before using optional tools. This is not meant to be a public marketing website.
-
-## Optional: Working in the CMS
-
-If CMS is enabled for you, open:
-
-```text
-https://<handle>.rizom.ai/cms
-```
-
-The CMS is a browser editor for your Rover content. It may ask for GitHub access because your content lives in a private GitHub repo.
-
-Use the CMS when you want to:
-
-- create or edit notes in the browser
-- add existing Markdown docs
-- browse structured content collections
-- make cleaner edits than you would in chat
-
-A good first CMS task is:
-
-1. open the **Notes** collection
-2. create a note titled `Why I’m using Rover`
-3. write 3 to 5 sentences
-4. save it
-5. refresh the CMS and confirm the note is still there
-
-If the CMS asks for GitHub access, use the fine-grained GitHub token for your private Rover content repo. If you were not given CMS/GitHub instructions, skip this section.
-
-## Optional: direct MCP access
-
-MCP is an optional way to connect Rover directly to an AI client that supports remote HTTP MCP.
-
-Use MCP only if we ask you to test it or if you already use a client that supports remote HTTP / Streamable HTTP MCP servers.
-
-We will send MCP connection details separately when MCP testing is enabled. The normal hosted MCP path is `https://<handle>.rizom.ai/mcp`, but use the exact server URL we send for your pilot.
-
-### What the MCP login flow looks like
-
-If your client supports OAuth / browser login, the normal flow is:
-
-1. In your MCP client, add a remote MCP server.
-2. Enter the Rover MCP server URL we sent you.
-3. The client discovers Rover's OAuth settings automatically.
-4. The client opens a browser window for Rover login.
-5. You sign in with your passkey.
-6. Rover asks you to approve client access.
-7. The client receives an access token automatically.
-8. You can use Rover tools from that client.
-
-You should not need to copy a setup link into the client. The setup link is only for registering your first passkey.
-
-If your client asks for a token or other credential, use only the MCP instructions we sent separately. Treat any MCP credentials like a password. Do not share them.
-
-### Client-specific notes
-
-Different MCP clients support remote HTTP and OAuth at different speeds. If you are using Claude Desktop, Cursor, VS Code, MCP Inspector, or another client, tell us the exact version before assuming it should work.
-
-### If MCP does not work
-
-Send us:
-
-- the client name
-- the client version
-- the exact error message
-- a screenshot if possible
-- the server URL you entered, without any secret token
-
-Do not paste your passkey setup link into an MCP client.
-
-## Optional: git, text files, and Obsidian
-
-Rover content can also live as normal markdown/text files in a private GitHub repo.
-
-This workflow is optional. Use it only if we explicitly enabled it for you or if you want more control.
-
-If enabled, we will:
-
-1. create or confirm your private content repo
-2. invite your GitHub account to that repo
-3. send you the repo URL
-4. explain whether to use GitHub Desktop, command-line git, Obsidian, or the CMS
-
-You do not need GitHub repo access just to use Rover in Discord.
-
-## Wishlist: when Rover cannot do something yet
-
-Rover has a built-in wishlist.
-
-If you ask for something Rover cannot do yet, it should explain the limitation and save the request as a wish. This helps us see which missing capabilities matter most.
-
-## What to expect in the pilot
-
-This is a real working system, but it is still an early pilot. Expect some rough edges, setup steps that may still be a bit manual, and improvements during the pilot.
-
-## Privacy and boundaries
-
-For the pilot:
-
-- your Rover is deployed specifically for you
-- browser/client access uses passkeys/OAuth where supported
-- if you are using MCP, we will send separate access instructions
-- your content repo is private when repo access is enabled
-- avoid putting highly sensitive material into the pilot unless we have explicitly agreed that it is in scope
-
-If you are unsure whether something belongs in Rover, ask us first.
-
-## Troubleshooting
-
-### I did not receive the setup email
-
-Check spam/promotions first. If it is not there, tell us which email address we should use.
-
-### The setup link expired or does not work
-
-Reply to your Rover operator. We can rotate/reissue setup.
-
-### I opened the domain and it does not look like a normal public site
-
-That is expected. The root URL is your Dashboard, not a public marketing site.
-
-### The browser asks me to use a passkey
-
-That is expected after setup. Use the same passkey you registered from the setup email.
-
-### My MCP client cannot connect
-
-Send us the client name, version, exact error message, and a screenshot if possible.
-
-### The CMS asks for GitHub auth and I am not sure what to do
-
-That is expected only if CMS is enabled for you. Use the GitHub token instructions we sent for your private Rover content repo. If you did not receive those instructions, ask us before continuing.
-
-## What feedback helps us most
-
-We especially want to hear:
-
-- what was confusing during setup
-- whether the setup email and passkey flow made sense
-- whether Discord and Dashboard made sense
-- what felt useful immediately
-- what felt weak, awkward, or unclear
-- what you expected Rover to do but could not get it to do
-- whether you would keep using it after the pilot
-
-Short, honest feedback is perfect.
-
-## Quick handoff template
-
-When we onboard you, the message will look roughly like this:
-
-```text
-Setup email: sent to <email>
-Onboarding guide: attached / linked
-Dashboard URL: https://<handle>.rizom.ai/
-Discord enabled: yes/no
-Discord setup: <invite link or setup steps>
-MCP access: optional / enabled / not enabled
-MCP setup: sent separately if enabled
-CMS enabled: yes/no
-CMS URL: https://<handle>.rizom.ai/cms
-Content repo access: yes/no
-```
-
-If anything is unclear, reply with the exact error text or a screenshot and we will help.
+A few plain sentences are perfect.