@rizom/ops 0.2.0-alpha.12 → 0.2.0-alpha.14

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
 
@@ -63,6 +70,37 @@ Use these checks after deploy:
 - 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
 
+## 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.
+- MCP is optional and mainly for direct client access or specific testing workflows.
+- 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
 
 Document known failure modes, recovery steps, and operator notes here.

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

@@ -10,10 +10,10 @@ Rover is your private AI assistant for working with your own notes, links, and i
 
 In this pilot, Rover is intentionally simple:
 
-- you talk to it through an **MCP client**
+- you will usually talk to it in **Discord**
 - **there is no website to browse**
-- Discord is optional
-- Obsidian fits through the git-sync/content-repo workflow, not as the main chat interface
+- **MCP is optional** and only needed for direct client access or specific testing workflows
+- your content can also live in a normal git repo of markdown/text files; **Obsidian is optional** if you want a nicer note-editing interface
 
 You can think of Rover as a private knowledge companion that helps you:
 
@@ -25,45 +25,66 @@ You can think of Rover as a private knowledge companion that helps you:
 
 ## What you will receive from us
 
-We will send you the details you need to connect.
+We will send you the details you need to get started.
 
 That usually includes:
 
-- your Rover URL: `https://<handle>.rizom.ai/mcp`
-- your **Bearer token**
-- confirmation of whether Discord is enabled for you
+- confirmation that Discord is enabled for you, plus the invite/setup steps
+- if needed, your Rover MCP URL: `https://<handle>.rizom.ai/mcp`
+- if needed, your **Bearer token**
 - if needed, an invite to your **private** Rover content repo
 - any extra instructions if we are testing a specific workflow with your cohort
 
-Treat the **Bearer token** like a password. Do not share it.
+If we give you a **Bearer token**, treat it like a password. Do not share it.
 
-## One important idea: MCP is just the connection method
+## One important idea: Discord is the default, MCP is optional
 
-If you have never used MCP before, the shortest explanation is:
+If you are new to Rover, the shortest explanation is:
 
 - **Rover** is the assistant
-- **MCP** is the way your AI client connects to Rover
+- **Discord** is the default way most pilot users will talk to it
+- **MCP** is an optional direct connection method for supported AI clients
 
-You do not need to understand the protocol details.
+You do not need to understand the protocol details unless we specifically ask you to use MCP.
 
-For the pilot, the practical meaning is simple:
+For most users, the practical meaning is simple:
 
-- open a supported client
-- add your Rover URL
-- paste your Bearer token
-- start talking to Rover
+- join Discord
+- message Rover there
+- start using it
+
+If your cohort is also testing MCP, we will send the URL, Bearer token, and setup help separately.
 
 ## What to use first
 
 For most users, the easiest first setup is:
 
-- **Claude Desktop** for talking to Rover
-- **Obsidian** only if you also want to work directly with markdown files later
-- **Discord** only if we explicitly enable it for you
+- **Discord** for talking to Rover
+- a normal **git repo of markdown/text files** only if you also want to work directly with your content later
+- **Obsidian** only if you want a friendlier interface for those same files
+- **Claude Desktop** or another MCP client only if we explicitly ask you to test a direct MCP workflow
+
+## Default setup: Discord
+
+For most users, getting started means:
+
+- join the Discord server we send you
+- open the Rover channel or DM
+- send a first message
+
+Try a first message like:
+
+> What can you help me do, and what should I use you for?
+
+Or:
+
+> Help me save my first note.
+
+If Discord is not enabled for you yet, tell us and we will share the right next step.
 
-## How to connect
+## Optional: direct MCP access
 
-Use an MCP client that supports:
+If we have asked you to use an MCP client, use one that supports:
 
 - **HTTP / Streamable HTTP MCP**
 - **Bearer token authentication**
@@ -78,9 +99,9 @@ If the client asks for a name, use something simple like:
 
 - `Rover (<handle>)`
 
-## Claude Desktop setup
+## Optional: Claude Desktop setup
 
-If your Claude Desktop version supports connecting to a **remote HTTP / Streamable HTTP MCP server**, enter:
+If we ask you to connect through Claude Desktop and your version supports a **remote HTTP / Streamable HTTP MCP server**, enter:
 
 - **Server URL:** `https://<handle>.rizom.ai/mcp`
 - **Authentication:** Bearer token
@@ -186,34 +207,38 @@ If Rover cannot do what you asked, a good response from Rover is something like:
 
 If that does **not** happen, that is useful feedback for us too.
 
-## Obsidian
+## Git, text files, and Obsidian
 
-Obsidian is part of the pilot through the **git-synced content repo workflow**, not through MCP.
+The underlying content workflow is a normal **git repo** with normal **markdown/text files**.
+
+Obsidian is optional. It is just one possible editor for those files.
 
 That means:
 
-- use **Claude Desktop** as the main way to talk to Rover
-- use **Obsidian** if you want to browse, draft, and edit markdown files directly
+- use **Discord** as the main way to talk to Rover
+- use a normal editor plus **git** if you want to browse, draft, and edit your files directly
+- use **Obsidian** only if you want a more note-focused interface for the same files
 - Rover can pick up those file changes through the normal git-sync / directory-sync flow
 
 A simple mental model:
 
-- **Claude Desktop** = talk to Rover
-- **Obsidian** = edit the underlying notes
+- **Discord** = talk to Rover
+- **git repo + text files** = the underlying content
+- **Obsidian** = an optional editor for that content
 
 ### Important: your content repo is private
 
-If you use the Obsidian/git workflow, you will be working in your own **private** GitHub repo.
+If you use the git/text-file workflow, you will be working in your own **private** GitHub repo.
 
 That means:
 
-- you do **not** need repo access just to use Rover through MCP
+- you do **not** need repo access just to use Rover in Discord or through MCP
 - you **do** need GitHub access if you want to clone, edit, and push to your content repo
 - we will invite you only to **your own** content repo, not to the operator repo and not to other users' repos
 
 ### How you get access
 
-If you want the Obsidian/git workflow, we will:
+If you want the git/text-file workflow, we will:
 
 1. create or confirm your private content repo
 2. invite your GitHub account to that repo
@@ -227,10 +252,9 @@ The easiest path for most first-time users is:
 1. install **GitHub Desktop**
 2. accept the repo invite in GitHub
 3. clone the private repo with GitHub Desktop
-4. open the cloned folder as an Obsidian vault
-5. optionally install the **Obsidian Git** plugin if you want in-app commit/push/pull support
-6. edit your markdown notes
-7. commit and push your changes
+4. open the cloned folder in your normal editor and edit the markdown/text files directly
+5. optionally open that same folder as an **Obsidian** vault if you prefer
+6. commit and push your changes
 
 ### Authentication options
 
@@ -242,38 +266,38 @@ Usually the easiest order is:
 2. **SSH key** if you already use git that way
 3. a **fine-grained personal access token** only if another tool specifically requires it
 
-You do **not** need a personal access token just to use Rover through MCP.
+You do **not** need a personal access token just to use Rover in Discord or through MCP.
 
 If we have already shared your content repo workflow with you, the normal setup is:
 
 1. clone your Rover content repo locally
-2. open that folder as an Obsidian vault
+2. edit the markdown/text files in your normal editor, or open that same folder as an Obsidian vault if you prefer
 3. optionally install the **Obsidian Git** plugin if you want in-app commit/push/pull support
-4. edit or organize your markdown notes there
-5. commit and push your changes through normal git or the Obsidian Git plugin
+4. edit or organize your notes there
+5. commit and push your changes through normal git, GitHub Desktop, or the Obsidian Git plugin
 6. let the normal git-sync flow carry those changes into Rover
 
-If we have **not** given you a direct content repo workflow yet, that is fine. You can ignore Obsidian for now and use Rover purely through MCP.
+If we have **not** given you a direct content repo workflow yet, that is fine. You can ignore git, text files, and Obsidian for now and use Rover in Discord. If we have also asked you to test MCP, you can use that too.
 
-## Discord (optional)
+## Discord (default)
 
-Discord is optional in this pilot.
+Discord is the default interface for this pilot.
 
-If it is enabled for you, think of it as a lightweight secondary interface for:
+Think of it as the main place to:
 
-- quick note capture
-- dropping in links to save
-- short questions when you do not want to open Claude Desktop
+- save quick notes
+- drop in links to save
+- ask short or long questions
+- use Rover day to day without setting up a separate client
 
 Important:
 
-- **MCP remains the main interface**
-- Discord is **off by default**
-- if you want Discord, tell us explicitly
-- for this pilot, Discord-enabled users may need to supply their own bot token
+- **Discord is the main pilot interface moving forward**
+- MCP is **optional**
 - if Discord is enabled, we will send the exact invite/setup steps separately
+- for some pilot setups, Discord-enabled users may need to supply their own bot token
 
-If Discord is **not** enabled for you, that is completely normal.
+If Discord is **not** enabled for you yet, ask us and we will tell you whether your cohort is on the Discord-first workflow.
 
 ## What to expect in the pilot
 
@@ -294,7 +318,7 @@ That is normal. The point of the pilot is to learn from real use.
 For the pilot:
 
 - your Rover is deployed specifically for you
-- access to `/mcp` is protected by your Bearer token
+- if you are using MCP, access to `/mcp` is protected by your Bearer token
 - you should 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.
@@ -303,9 +327,9 @@ If you are unsure whether something belongs in Rover, ask us first.
 
 ### I opened the domain and it does not look like a normal site
 
-That is expected. In this pilot, **there is no website to browse**. Rover core is MCP-first.
+That is expected. In this pilot, **there is no website to browse**. Rover runs through Discord and, optionally, a direct MCP endpoint.
 
-### I got an authentication error
+### I got an authentication error in MCP
 
 Usually this means one of three things:
 
@@ -347,10 +371,14 @@ Short, honest feedback is perfect.
 When we onboard you, the message will look roughly like this:
 
 ```text
-Rover URL: https://<handle>.rizom.ai/mcp
+Discord enabled: yes/no
+Discord setup: <invite link or setup steps>
+MCP access: optional / enabled / not enabled
+
+If MCP is enabled:
+MCP URL: https://<handle>.rizom.ai/mcp
 Auth type: Bearer token
 Bearer token: <token>
-Discord enabled: yes/no
 ```
 
 If anything is unclear, reply with the exact error text or a screenshot and we will help.

package/templates/rover-pilot/package.json

@@ -3,6 +3,9 @@
   "private": true,
   "type": "module",
   "packageManager": "bun@__BUN_VERSION__",
+  "dependencies": {
+    "age-encryption": "^0.3.0"
+  },
   "devDependencies": {
     "@rizom/ops": "__BRAINS_OPS_VERSION__"
   }

package/templates/rover-pilot/pilot.yaml

@@ -6,3 +6,6 @@ contentRepoPrefix: rover-
 domainSuffix: .rizom.ai
 preset: core
 aiApiKey: AI_API_KEY
+gitSyncToken: GIT_SYNC_TOKEN
+mcpAuthToken: MCP_AUTH_TOKEN
+agePublicKey: age1replace-with-your-public-key

package/templates/rover-pilot/users/alice.yaml

@@ -3,4 +3,5 @@ anchorProfile:
   name: Alice Example
   description: Replace this with Alice's real public profile summary.
 discord:
-  enabled: false
+  enabled: true
+  # anchorUserId: "123456789012345678"

package/dist/user-secret-names.d.ts

@@ -1,6 +0,0 @@
-export interface UserSecretNames {
-    gitSyncTokenSecretName: string;
-    mcpAuthTokenSecretName: string;
-    discordBotTokenSecretName: string;
-}
-export declare function deriveUserSecretNames(handle: string): UserSecretNames;