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

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

@@ -2,339 +2,316 @@
 
 Welcome to the Rover pilot.
 
-This document is written for **first-time users**. You do **not** need prior experience with Rover, MCP, git, or the rest of the system to get started.
+This guide is for first-time Rover users. You do not need prior experience with Rover, MCP, git, GitHub, or Obsidian to get started.
 
 ## What Rover is
 
 Rover is your private AI assistant for working with your own notes, links, and ideas.
 
-In this pilot, Rover is intentionally simple:
+For the current pilot, the normal core experience is:
 
-- you talk to it through an **MCP client**
-- **there is no website to browse**
-- Discord is optional
-- Obsidian fits through the git-sync/content-repo workflow, not as the main chat interface
+- **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
 
-You can think of Rover as a private knowledge companion that helps you:
+Some users may also receive:
 
-- save notes
-- save links
-- reflect on your own material
-- find patterns in what you have collected
-- think through questions with AI
+- **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 you will receive from us
-
-We will send you the details you need to connect.
-
-That usually includes:
-
-- your Rover URL: `https://<handle>.rizom.ai/mcp`
-- your **Bearer token**
-- confirmation of whether Discord is enabled for you
-- if needed, an invite to your **private** Rover content repo
-- any extra instructions if we are testing a specific workflow with your cohort
+If we did not explicitly give you CMS, GitHub, MCP, or Obsidian instructions, you can ignore those sections for now.
 
-Treat the **Bearer token** like a password. Do not share it.
+## Start here: setup
 
-## One important idea: MCP is just the connection method
+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.
 
-If you have never used MCP before, the shortest explanation is:
+## Your setup email
 
-- **Rover** is the assistant
-- **MCP** is the way your AI client connects to Rover
+The setup email contains a single-use passkey setup link.
 
-You do not need to understand the protocol details.
+Treat that link like a temporary password:
 
-For the pilot, the practical meaning is simple:
+- do not forward it
+- use it once
+- expect it to expire
+- ask us for help if it has expired or does not work
 
-- open a supported client
-- add your Rover URL
-- paste your Bearer token
-- start talking to Rover
+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.
 
-## What to use first
+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.
 
-For most users, the easiest first setup is:
+## Your first Rover session
 
-- **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
+Start in **Discord** if it is enabled for your pilot. That is the normal first interface.
 
-## How to connect
+### 1. Say hello
 
-Use an MCP client that supports:
+Send:
 
-- **HTTP / Streamable HTTP MCP**
-- **Bearer token authentication**
+> What can you help me do, and what should I use you for?
 
-When your client asks for connection details, use:
+Rover should answer with a short overview of what it can do.
 
-- **Server URL:** `https://<handle>.rizom.ai/mcp`
-- **Authentication type:** Bearer token
-- **Bearer token:** the token we sent you
+### 2. Create your first note
 
-If the client asks for a name, use something simple like:
+Ask Rover to save a simple note:
 
-- `Rover (<handle>)`
+> Save a note: I am trying Rover because I want a better way to collect ideas, links, and questions in one place.
 
-## Claude Desktop setup
+Or:
 
-If your Claude Desktop version supports connecting to a **remote HTTP / Streamable HTTP MCP server**, enter:
+> Help me save my first note.
 
-- **Server URL:** `https://<handle>.rizom.ai/mcp`
-- **Authentication:** Bearer token
-- **Token:** the token we sent you
+### 3. Add your first link
 
-Then try a first message like:
+Send Rover a link you want to remember:
 
-> What can you help me do, and what should I use you for?
+> Save this link and tell me why it might be useful later: https://example.com
 
 Or:
 
-> Help me save my first note.
+> Add this as a link about tools I want to revisit: https://example.com
 
-If your Claude Desktop version only supports local MCP servers and not remote HTTP MCP cleanly, tell us what version you are using and we will help you.
+Rover should save the link and, when possible, keep a short description of why it matters.
 
-## Your first 5 minutes
+### 4. Upload an existing Markdown doc
 
-Once you are connected, try this sequence:
+If you already have notes or docs in Markdown, you do not need to retype them.
 
-### 1. Check that Rover responds
+Upload a `.md` file and ask Rover to save or import it:
 
-Ask:
+> Save this Markdown doc in my notes.
 
-> What can you help me do?
+Or:
 
-### 2. Save a first note
+> Import this doc and tell me what it is about.
 
-Ask:
+This is often the fastest way to give Rover useful context.
 
-> Save a note: I want to use Rover to collect ideas from my work, reading, and conversations.
+### 5. Ask Rover about what you just added
 
-### 3. Save a useful link
+After you have saved a note, link, or Markdown doc, ask Rover to reflect it back:
 
-Ask:
+> What have I added so far?
 
-> Save this link and note why it matters to me: <paste URL>
+Or:
 
-### 4. Ask Rover to reflect back what it knows
+> What do you know about what I am interested in so far?
 
-Ask:
+This is the basic Rover loop: add material, then ask Rover to help you think with it.
 
-> Based on what I’ve stored so far, what themes are starting to emerge?
+### 6. Try a more useful task
 
-### 5. Use it as a thinking partner
+Once Rover has a little context, try one of these:
 
-Ask:
+> Summarize my notes so far.
 
-> I am thinking through a problem in my work. Help me structure the question and identify what context is missing.
+> What themes do you see in what I have added?
 
-## Wishlist: when Rover cannot do something yet
+> Turn my rough note into a clearer paragraph.
 
-Rover has a built-in **wishlist**.
+> Help me make a small reading list from the links I saved.
 
-This is important for first-time users because Rover will not be able to do everything yet.
+These examples show the main scope of Rover: saving material, organizing it, reflecting on it, and helping you make something from it.
 
-If you ask for something Rover cannot do, it should add that request to the wishlist instead of just failing silently.
+### 7. Ask another agent
 
-You can think of the wishlist as:
+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.
 
-- a backlog of missing capabilities
-- a record of things users want Rover to do
-- a way for the pilot team to see which missing features matter most
+## The default mental model
 
-### When the wishlist is useful
+If you remember only one thing, remember this:
 
-The wishlist is especially useful when you ask Rover to do something like:
+- **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
 
-- connect to a tool it does not support yet
-- perform an action it cannot perform yet
-- add a workflow or feature that does not exist yet
+## What you will receive from us
 
-Examples:
+Depending on your pilot cohort, we will send you some or all of these:
 
-> I want Rover to draft and send emails for me.
+- 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
 
-> I want Rover to connect to my calendar.
+Keep setup links, GitHub tokens, and any MCP credentials separate. Do not paste the passkey setup link into an MCP client.
 
-> I want Rover to summarize voice notes automatically.
+## Discord
 
-If Rover cannot actually do those things yet, it should tell you that and add the request to the wishlist.
+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.
 
-### What happens when something is added to the wishlist
+Use it to:
 
-When a request is added to the wishlist:
+- save quick notes
+- drop in links
+- ask questions
+- use Rover day to day without setting up a separate client
 
-- it is saved as a **wish**
-- it starts in a **new** state
-- similar requests can be grouped together instead of creating endless duplicates
-- repeated demand can increase the count of how many times that wish was requested
+If Discord is enabled, we will send the exact invite/setup steps separately.
 
-That helps us see which gaps are one-off ideas and which ones keep coming up across real usage.
+## Dashboard basics
 
-### How you should use it
+The Dashboard is the browser landing page for your Rover.
 
-You do **not** need special commands.
+Open it at:
 
-Just ask naturally.
+```text
+https://<handle>.rizom.ai/
+```
 
-If Rover cannot do what you asked, a good response from Rover is something like:
+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.
 
-- it explains the limitation clearly
-- it says the request was added to the wishlist
+## Optional: Working in the CMS
 
-If that does **not** happen, that is useful feedback for us too.
+If CMS is enabled for you, open:
 
-## Obsidian
+```text
+https://<handle>.rizom.ai/cms
+```
 
-Obsidian is part of the pilot through the **git-synced content repo workflow**, not through MCP.
+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.
 
-That means:
+Use the CMS when you want to:
 
-- use **Claude Desktop** as the main way to talk to Rover
-- use **Obsidian** if you want to browse, draft, and edit markdown files directly
-- Rover can pick up those file changes through the normal git-sync / directory-sync flow
+- create or edit notes in the browser
+- add existing Markdown docs
+- browse structured content collections
+- make cleaner edits than you would in chat
 
-A simple mental model:
+A good first CMS task is:
 
-- **Claude Desktop** = talk to Rover
-- **Obsidian** = edit the underlying notes
+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
 
-### Important: your content repo is private
+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.
 
-If you use the Obsidian/git workflow, you will be working in your own **private** GitHub repo.
+## Optional: direct MCP access
 
-That means:
+MCP is an optional way to connect Rover directly to an AI client that supports remote HTTP MCP.
 
-- you do **not** need repo access just to use Rover 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
+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.
 
-### How you get access
+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.
 
-If you want the Obsidian/git workflow, we will:
+### What the MCP login flow looks like
 
-1. create or confirm your private content repo
-2. invite your GitHub account to that repo
-3. ask you to accept the GitHub invite
-4. send you the repo URL
+If your client supports OAuth / browser login, the normal flow is:
 
-### Easiest setup for most users
+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.
 
-The easiest path for most first-time users is:
+You should not need to copy a setup link into the client. The setup link is only for registering your first passkey.
 
-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
+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.
 
-### Authentication options
+### Client-specific notes
 
-To work with a private repo, you need GitHub authentication.
+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.
 
-Usually the easiest order is:
+### If MCP does not work
 
-1. **GitHub Desktop** or normal GitHub sign-in
-2. **SSH key** if you already use git that way
-3. a **fine-grained personal access token** only if another tool specifically requires it
+Send us:
 
-You do **not** need a personal access token just to use Rover through MCP.
+- the client name
+- the client version
+- the exact error message
+- a screenshot if possible
+- the server URL you entered, without any secret token
 
-If we have already shared your content repo workflow with you, the normal setup is:
+Do not paste your passkey setup link into an MCP client.
 
-1. clone your Rover content repo locally
-2. open that folder as an Obsidian vault
-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
-6. let the normal git-sync flow carry those changes into Rover
+## Optional: git, text files, and Obsidian
 
-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.
+Rover content can also live as normal markdown/text files in a private GitHub repo.
 
-## Discord (optional)
+This workflow is optional. Use it only if we explicitly enabled it for you or if you want more control.
 
-Discord is optional in this pilot.
+If enabled, we will:
 
-If it is enabled for you, think of it as a lightweight secondary interface for:
+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
 
-- quick note capture
-- dropping in links to save
-- short questions when you do not want to open Claude Desktop
+You do not need GitHub repo access just to use Rover in Discord.
 
-Important:
+## Wishlist: when Rover cannot do something yet
 
-- **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
-- if Discord is enabled, we will send the exact invite/setup steps separately
+Rover has a built-in wishlist.
 
-If Discord is **not** enabled for you, that is completely normal.
+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.
-
-So you should expect:
-
-- some rough edges
-- a setup process that may still be a bit manual
-- a Rover that becomes more useful as you add more notes and links
-- occasional follow-up questions from us about your experience
-- improvements and changes during the pilot
-
-That is normal. The point of the pilot is to learn from real use.
+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
-- 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
+- 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 opened the domain and it does not look like a normal site
+### I did not receive the setup email
 
-That is expected. In this pilot, **there is no website to browse**. Rover core is MCP-first.
+Check spam/promotions first. If it is not there, tell us which email address we should use.
 
-### I got an authentication error
+### The setup link expired or does not work
 
-Usually this means one of three things:
+Reply to your Rover operator. We can rotate/reissue setup.
 
-- the Bearer token was missing
-- the Bearer token was pasted incorrectly
-- the client is using the wrong authentication type
+### I opened the domain and it does not look like a normal public site
 
-Double-check that you are using:
+That is expected. The root URL is your Dashboard, not a public marketing site.
 
-- URL: `https://<handle>.rizom.ai/mcp`
-- auth type: **Bearer token**
-- token: exactly the token we sent you
+### The browser asks me to use a passkey
 
-### My MCP client says it cannot connect
+That is expected after setup. Use the same passkey you registered from the setup email.
 
-Some clients support local MCP servers better than remote HTTP MCP servers.
+### My MCP client cannot connect
 
-If that happens, send us:
+Send us the client name, version, exact error message, and a screenshot if possible.
 
-- the name of the client
-- the version you are using
-- the exact error message
-- 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
@@ -347,10 +324,16 @@ Short, honest feedback is perfect.
 When we onboard you, the message will look roughly like this:
 
 ```text
-Rover URL: https://<handle>.rizom.ai/mcp
-Auth type: Bearer token
-Bearer token: <token>
+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.

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
+contentRepoAdminToken: CONTENT_REPO_ADMIN_TOKEN
+agePublicKey: age1replace-with-your-public-key

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

@@ -1,3 +1,7 @@
 handle: alice
+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;

package/templates/rover-pilot/.kamal/hooks/pre-deploy

@@ -1,9 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-BRAIN_FILE="${BRAIN_YAML_PATH:-brain.yaml}"
-SSH_USER="$(ruby -e 'require "yaml"; config = YAML.load_file("deploy/kamal/deploy.yml") || {}; puts(config.dig("ssh", "user") || "root")')"
-IFS=',' read -ra HOSTS <<< "$KAMAL_HOSTS"
-for host in "${HOSTS[@]}"; do
-  scp -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null "$BRAIN_FILE" "${SSH_USER}@${host}:/opt/brain.yaml"
-done