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

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

@@ -1,356 +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 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 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:
 
-In this pilot, Rover is intentionally simple:
+   > What can you help me do?
 
-- 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
+That's the whole setup. The chat in your browser is where you and
+Rover will spend most of your time.
 
-You can think of Rover as a private knowledge companion that helps you:
+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.
 
-- save notes
-- save links
-- reflect on your own material
-- find patterns in what you have collected
-- think through questions with AI
+## What your Rover holds
 
-## What you will receive from us
+Everything in Rover is one of a few simple kinds of things:
 
-We will send you the details you need to connect.
+- **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.
 
-That usually includes:
+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 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
+## The way of working
 
-Treat the **Bearer token** like a password. Do not share it.
+Rover is built around a simple loop:
 
-## One important idea: MCP is just the connection method
+**Capture → ask back → shape.**
 
-If you have never used MCP before, the shortest explanation is:
+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.
 
-- **Rover** is the assistant
-- **MCP** is the way your AI client connects to Rover
+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.
 
-You do not need to understand the protocol details.
+### Capture
 
-For the pilot, the practical meaning is simple:
+Notes for what's in your head:
 
-- open a supported client
-- add your Rover URL
-- paste your Bearer token
-- start talking to Rover
+> Save a note: I keep explaining the same idea to clients — maybe
+> it should be a workshop.
 
-## What to use first
+Links for what's on your screen:
 
-For most users, the easiest first setup is:
+> Save this link with my workshop idea — it's how someone else
+> structures theirs: https://example.com
 
-- **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
+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.
 
-## How to connect
+### Ask back
 
-Use an MCP client that supports:
+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:
 
-- **HTTP / Streamable HTTP MCP**
-- **Bearer token authentication**
+> What have I added about the workshop idea?
 
-When your client asks for connection details, use:
+> What did I save this week?
 
-- **Server URL:** `https://<handle>.rizom.ai/mcp`
-- **Authentication type:** Bearer token
-- **Bearer token:** the token we sent you
+And as material accumulates, the topics surface — the themes you
+keep returning to without noticing:
 
-If the client asks for a name, use something simple like:
+> What themes do you see in what I've collected?
 
-- `Rover (<handle>)`
+### Shape
 
-## Claude Desktop setup
+When you want to make something from what you've gathered:
 
-If your Claude Desktop version supports connecting to a **remote HTTP / Streamable HTTP MCP server**, enter:
+> Turn my workshop notes into a one-page outline.
 
-- **Server URL:** `https://<handle>.rizom.ai/mcp`
-- **Authentication:** Bearer token
-- **Token:** the token we sent you
+> Make a reading list from the links I saved.
 
-Then try a first message like:
+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.
 
-> What can you help me do, and what should I use you for?
+## When Rover can't do something: make a wish
 
-Or:
+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:
 
-> Help me save my first note.
+> I wish you could remind me about this next Monday.
 
-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.
+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.
 
-## Your first 5 minutes
+## Your Rover in the network
 
-Once you are connected, try this sequence:
+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.
 
-### 1. Check that Rover responds
+**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:
 
-Ask:
+> Add yeehaa.io to my agents.
 
-> What can you help me do?
+Then ask questions that put their knowledge next to yours:
 
-### 2. Save a first note
+> Ask yeehaa.io what they've published about designing workshops,
+> and compare it with my own workshop notes.
 
-Ask:
+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:
 
-> Save a note: I want to use Rover to collect ideas from my work, reading, and conversations.
+> Save that comparison as a note with my workshop idea.
 
-### 3. Save a useful link
+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.
 
-Ask:
+**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.
 
-> Save this link and note why it matters to me: <paste URL>
+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.
 
-### 4. Ask Rover to reflect back what it knows
+## The other doors
 
-Ask:
+Chat is the primary interface, but your Rover has a few more
+entrances. All optional — ignore them until you're curious:
 
-> Based on what I’ve stored so far, what themes are starting to emerge?
+- **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.
 
-### 5. Use it as a thinking partner
+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.
 
-Ask:
+## What to expect from the pilot
 
-> I am thinking through a problem in my work. Help me structure the question and identify what context is missing.
+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.
 
-## Wishlist: when Rover cannot do something yet
+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.
 
-Rover has a built-in **wishlist**.
+## If something doesn't work
 
-This is important for first-time users because Rover will not be able to do everything yet.
+- **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 ask for something Rover cannot do, it should add that request to the wishlist instead of just failing silently.
+## Tell us what you notice
 
-You can think of the wishlist as:
+The feedback that helps most is small and honest — drop it in the
+Discord server as it occurs to you:
 
-- 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
+- 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
 
-### When the wishlist is useful
-
-The wishlist is especially useful when you ask Rover to do something like:
-
-- 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
-
-Examples:
-
-> I want Rover to draft and send emails for me.
-
-> I want Rover to connect to my calendar.
-
-> I want Rover to summarize voice notes automatically.
-
-If Rover cannot actually do those things yet, it should tell you that and add the request to the wishlist.
-
-### What happens when something is added to the wishlist
-
-When a request is added to the wishlist:
-
-- 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
-
-That helps us see which gaps are one-off ideas and which ones keep coming up across real usage.
-
-### How you should use it
-
-You do **not** need special commands.
-
-Just ask naturally.
-
-If Rover cannot do what you asked, a good response from Rover is something like:
-
-- it explains the limitation clearly
-- it says the request was added to the wishlist
-
-If that does **not** happen, that is useful feedback for us too.
-
-## Obsidian
-
-Obsidian is part of the pilot through the **git-synced content repo workflow**, not through MCP.
-
-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
-- 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
-
-### Important: your content repo is private
-
-If you use the Obsidian/git 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** 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:
-
-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
-
-### Easiest setup for most users
-
-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
-
-### Authentication options
-
-To work with a private repo, you need GitHub authentication.
-
-Usually the easiest order is:
-
-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
-
-You do **not** need a personal access token just to use Rover 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
-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
-
-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.
-
-## Discord (optional)
-
-Discord is optional in this pilot.
-
-If it is enabled for you, think of it as a lightweight secondary interface for:
-
-- quick note capture
-- dropping in links to save
-- short questions when you do not want to open Claude Desktop
-
-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
-- if Discord is enabled, we will send the exact invite/setup steps separately
-
-If Discord is **not** enabled for you, that is completely normal.
-
-## 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.
-
-## 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
-
-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
-
-That is expected. In this pilot, **there is no website to browse**. Rover core is MCP-first.
-
-### I got an authentication error
-
-Usually this means one of three things:
-
-- the Bearer token was missing
-- the Bearer token was pasted incorrectly
-- the client is using the wrong authentication type
-
-Double-check that you are using:
-
-- URL: `https://<handle>.rizom.ai/mcp`
-- auth type: **Bearer token**
-- token: exactly the token we sent you
-
-### My MCP client says it cannot connect
-
-Some clients support local MCP servers better than remote HTTP MCP servers.
-
-If that happens, send us:
-
-- the name of the client
-- the version you are using
-- the exact error message
-- a screenshot if possible
-
-## What feedback helps us most
-
-We especially want to hear:
-
-- what was confusing during setup
-- 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
-Rover 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.
+A few plain sentences are perfect.

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

@@ -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;

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

package/templates/rover-pilot/deploy/Caddyfile

@@ -1,72 +0,0 @@
-# Internal Caddy — path-based routing to brain services.
-# kamal-proxy terminates TLS externally; this runs inside the container.
-:80 {
-	@preview host preview.*
-	handle @preview {
-		reverse_proxy localhost:4321
-
-		header {
-			X-Frame-Options "SAMEORIGIN"
-			X-Content-Type-Options "nosniff"
-			Referrer-Policy "strict-origin-when-cross-origin"
-		}
-	}
-
-	# Health endpoint
-	handle /health {
-		reverse_proxy localhost:3333
-	}
-
-	# MCP endpoint
-	handle /mcp* {
-		reverse_proxy localhost:3333
-
-		header {
-			X-Content-Type-Options "nosniff"
-			Access-Control-Allow-Origin "*"
-			Access-Control-Allow-Methods "GET, POST, DELETE, OPTIONS"
-			Access-Control-Allow-Headers "Content-Type, Authorization, MCP-Session-Id"
-		}
-	}
-
-	# A2A endpoints
-	handle /.well-known/agent-card.json {
-		reverse_proxy localhost:3334
-	}
-
-	handle /a2a {
-		reverse_proxy localhost:3334
-
-		header {
-			X-Content-Type-Options "nosniff"
-			Access-Control-Allow-Origin "*"
-			Access-Control-Allow-Methods "GET, POST, OPTIONS"
-			Access-Control-Allow-Headers "Content-Type, Authorization"
-		}
-	}
-
-	# Plugin API routes
-	handle /api/* {
-		reverse_proxy localhost:3335
-	}
-
-	@root path /
-	handle @root {
-		redir /.well-known/agent-card.json 302
-	}
-
-	# Production site: prefer the webserver when present; otherwise fall back
-	# to the A2A interface so core-only deployments never return a bare 502.
-	handle {
-		reverse_proxy localhost:8080 localhost:3334 {
-			lb_policy first
-			lb_retries 1
-		}
-
-		header {
-			X-Frame-Options "SAMEORIGIN"
-			X-Content-Type-Options "nosniff"
-			Referrer-Policy "strict-origin-when-cross-origin"
-		}
-	}
-}