@rizom/ops 0.2.0-alpha.22 → 0.2.0-alpha.221

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

@@ -1,384 +1,119 @@
-# Rover Pilot User Onboarding
+# Welcome to Rover
 
-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.
+Most of us have more thinking happening than we can hold onto. Ideas show up in the wrong moment, notes land in five different places, and half of what you've figured out is effectively invisible by the time you need it again.
 
-## 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:
-
-- you will usually talk to it in **Discord**
-- **there is no website to browse**
-- **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:
-
-- save notes
-- save links
-- reflect on your own material
-- find patterns in what you have collected
-- think through questions with AI
-
-## What you will receive from us
-
-We will send you the details you need to get started.
-
-That usually includes:
-
-- 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
-
-If we give you a **Bearer token**, treat it like a password. Do not share it.
-
-## One important idea: Discord is the default, MCP is optional
-
-If you are new to Rover, the shortest explanation is:
-
-- **Rover** is the assistant
-- **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 unless we specifically ask you to use MCP.
-
-For most users, the practical meaning is simple:
-
-- 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:
-
-- **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.
-
-## Optional: direct MCP access
-
-If we have asked you to use an MCP client, use one that supports:
-
-- **HTTP / Streamable HTTP MCP**
-- **Bearer token authentication**
-
-When your client asks for connection details, use:
-
-- **Server URL:** `https://<handle>.rizom.ai/mcp`
-- **Authentication type:** Bearer token
-- **Bearer token:** the token we sent you
-
-If the client asks for a name, use something simple like:
-
-- `Rover (<handle>)`
-
-## Optional: Claude Desktop setup
-
-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
-- **Token:** the token we sent you
-
-Then 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 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.
-
-## Your first 5 minutes
-
-Once you are connected, try this sequence:
-
-### 1. Check that Rover responds
-
-Ask:
-
-> What can you help me do?
-
-### 2. Save a first note
-
-Ask:
+Rover is built for that problem. It's a private space where your thinking accumulates — notes, links, fragments, half-formed ideas — and an AI that can work with all of it. Find things you saved months ago. Connect dots across topics. Turn a rough note into a draft. The more you put in, the more useful it gets. And if another Rover user is in your network, your Rovers can talk to each other — share knowledge, work on something together — just by asking.
 
-> Save a note: I want to use Rover to collect ideas from my work, reading, and conversations.
+---
 
-### 3. Save a useful link
-
-Ask:
-
-> Save this link and note why it matters to me: <paste URL>
-
-### 4. Ask Rover to reflect back what it knows
-
-Ask:
-
-> Based on what I’ve stored so far, what themes are starting to emerge?
-
-### 5. Use it as a thinking partner
-
-Ask:
-
-> I am thinking through a problem in my work. Help me structure the question and identify what context is missing.
-
-## Wishlist: when Rover cannot do something yet
-
-Rover has a built-in **wishlist**.
-
-This is important for first-time users because Rover will not be able to do everything yet.
-
-If you ask for something Rover cannot do, it should add that request to the wishlist instead of just failing silently.
-
-You can think of the wishlist as:
-
-- 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
-
-### 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.
-
-## Git, text files, and Obsidian
-
-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 **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:
-
-- **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 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 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 git/text-file 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:
+## What Rover 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 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
+Rover is your private knowledge companion. It holds your notes, links, and ideas — and helps you think with them, not just store them.
 
-### Authentication options
+Ask it a question and it searches what you've saved. Give it a fragment of thinking and it can help you turn it into something.
 
-To work with a private repo, you need GitHub authentication.
+---
 
-Usually the easiest order is:
+## Getting in
 
-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
+We'll send you a personal URL — something like `https://<handle>.rizom.ai/`.
 
-You do **not** need a personal access token just to use Rover in Discord or through MCP.
+When you open it for the first time, you'll be asked to set a passkey. Do that once and you're in. No passwords to remember.
 
-If we have already shared your content repo workflow with you, the normal setup is:
+From there, your three main interfaces are:
 
-1. clone your Rover content repo locally
-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 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
+- **Chat** (`/chat`) — where you talk to Rover
+- **Dashboard** (`/`) — an overview of your Rover
+- **CMS** (`/cms`) — a browser editor for your content
 
-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.
+Start with Chat. Everything else follows from there.
 
-## Discord (default)
+---
 
-Discord is the default interface for this pilot.
+## Your first five minutes
 
-Think of it as the main place to:
+1. Open your Chat URL. A good first message:
+   > Help me save my first note.
+2. Save something — a thought, a link, an idea. Doesn't need to be polished.
+3. Ask Rover about it. See what comes back.
 
-- save quick notes
-- drop in links to save
-- ask short or long questions
-- use Rover day to day without setting up a separate client
+That loop — save, ask, get something useful back — is the core of how Rover works.
 
-Important:
+---
 
-- **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
+## The Chat and the CMS: when to use which
 
-If Discord is **not** enabled for you yet, ask us and we will tell you whether your cohort is on the Discord-first workflow.
+**Chat** is for thinking out loud, asking questions, saving things quickly, and using Rover as a day-to-day thinking partner.
 
-## What to expect in the pilot
+**CMS** is for when you want to deliberately create or edit content — browsing your notes, making clean edits, working more like an editor than a conversationalist.
 
-This is a real working system, but it is still an early pilot.
+Most people spend most of their time in Chat. The CMS becomes useful once you have something worth editing.
 
-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
+## Other ways to chat with Rover
 
-That is normal. The point of the pilot is to learn from real use.
+`/chat` is the primary interface, but Rover can also be reached through messaging platforms. Discord is tested and working. Slack, WhatsApp Business, and similar should work out of the box — we'll send setup steps if that's part of your configuration.
 
-## Privacy and boundaries
+**Talking to another Rover**
 
-For the pilot:
+If you know another Rover user, you can add them to your contacts and call their Rover directly from your chat.
 
-- your Rover is deployed specifically for you
-- 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
+- To add: _Add jane.rizom.ai to my contacts._
+- To call: _Call jane.rizom.ai and ask [your question]._
+  You'll need their address — in the format `name.rizom.ai` — which they can share with you directly.
 
-If you are unsure whether something belongs in Rover, ask us first.
+---
 
-## Troubleshooting
+## Connecting Rover to other tools
 
-### I opened the domain and it does not look like a normal site
+Rover can connect to external tools via MCP — a standard protocol that works in two directions: agentic AI clients (like Claude Desktop) can use it to talk to Rover, and Rover can use it to talk to productivity tools like Notion or Linear.
 
-That is expected. In this pilot, **there is no website to browse**. Rover runs through Discord and, optionally, a direct MCP endpoint.
+Plugins exist for a number of tools already, and new ones can be built quickly in response to what you actually need. If there's a tool you'd want Rover to connect to, tell us.
 
-### I got an authentication error in MCP
+If MCP is part of your setup, we'll send specific instructions alongside your URL.
 
-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
+## A few common questions
 
-Double-check that you are using:
+**How do I access my data?**
+Your primary interface is the CMS (`/cms`), where you can browse and edit everything you've saved. If you're set up with GitHub access, your content also lives in a private repository you can access directly.
 
-- URL: `https://<handle>.rizom.ai/mcp`
-- auth type: **Bearer token**
-- token: exactly the token we sent you
+**Does Rover connect to the internet?**
+No — and that's intentional. Rover works with what you've put into it, not with whatever the internet currently says. That means its answers are grounded in your actual knowledge base, not in generic search results.
 
-### My MCP client says it cannot connect
+**What does this cost?**
+Nothing during the pilot. We cover hosting costs while you're part of the programme.
 
-Some clients support local MCP servers better than remote HTTP MCP servers.
+---
 
-If that happens, send us:
+## This is a pilot
 
-- the name of the client
-- the version you are using
-- the exact error message
-- a screenshot if possible
+Rover works. But it's not finished.
 
-## What feedback helps us most
+You'll hit rough edges. Some things you try won't work. Some things you expect to be there won't be yet. That's normal — and it's actually why you're here.
 
-We especially want to hear:
+There's a ceiling on how much Rover can improve without real people using it on real problems. We've reached that ceiling on our own. Your usage is what lets the product become what it's capable of becoming. A single Rover in isolation can only do so much — the network only becomes real when there are enough active, populated Rovers in it.
 
-- 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
+Rover has a built-in wishlist. If you ask it to do something it can't do yet, it should tell you clearly and log the request — that goes back to us as a signal for where the product needs to go next.
 
-Short, honest feedback is perfect.
+When something breaks or falls short, tell us: what you were trying to do, what you expected, and what happened instead.
 
-## Quick handoff template
+---
 
-When we onboard you, the message will look roughly like this:
+## Your access details
 
-```text
-Discord enabled: yes/no
-Discord setup: <invite link or setup steps>
-MCP access: optional / enabled / not enabled
+When we onboard you, we'll send something like:
 
-If MCP is enabled:
-MCP URL: https://<handle>.rizom.ai/mcp
-Auth type: Bearer token
-Bearer token: <token>
+```
+Chat URL: https://<handle>.rizom.ai/chat
+Dashboard URL: https://<handle>.rizom.ai/
+CMS URL: https://<handle>.rizom.ai/cms
+Discord: yes/no — setup steps below if yes
+MCP: enabled/not enabled — details below if enabled
 ```
 
-If anything is unclear, reply with the exact error text or a screenshot and we will help.
+If anything is unclear, reply with what you're seeing and we'll help.

package/templates/rover-pilot/pilot.yaml

@@ -7,5 +7,5 @@ domainSuffix: .rizom.ai
 preset: core
 aiApiKey: AI_API_KEY
 gitSyncToken: GIT_SYNC_TOKEN
-mcpAuthToken: MCP_AUTH_TOKEN
+contentRepoAdminToken: CONTENT_REPO_ADMIN_TOKEN
 agePublicKey: age1replace-with-your-public-key

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/Dockerfile

@@ -1,30 +0,0 @@
-ARG BUN_VERSION=1.3.10
-FROM oven/bun:${BUN_VERSION}-slim AS runtime
-
-WORKDIR /app
-
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    curl ca-certificates git \
-    && rm -rf /var/lib/apt/lists/*
-
-ENV XDG_DATA_HOME=/data
-ENV XDG_CONFIG_HOME=/config
-RUN mkdir -p /app/data /app/cache /app/brain-data && \
-    chmod -R 777 /app/data /app/cache /app/brain-data
-
-EXPOSE 8080
-
-CMD ["./node_modules/.bin/brain", "start"]
-
-# --- standalone: bake full project into image (brain-cli deploy) ---
-FROM runtime AS standalone
-COPY package.json ./package.json
-RUN bun install --production --ignore-scripts
-COPY . .
-
-# --- fleet: install published brain at pinned version (ops deploy) ---
-FROM runtime AS fleet
-ARG BRAIN_VERSION
-RUN test -n "$BRAIN_VERSION" \
- && printf '{"name":"rover-pilot-runtime","private":true}\n' > package.json \
- && bun add @rizom/brain@$BRAIN_VERSION

package/templates/rover-pilot/deploy/kamal/deploy.yml

@@ -1,40 +0,0 @@
-service: rover
-image: <%= ENV['IMAGE_REPOSITORY'] %>
-
-servers:
-  web:
-    hosts:
-      - <%= ENV['SERVER_IP'] %>
-
-proxy:
-  ssl:
-    certificate_pem: CERTIFICATE_PEM
-    private_key_pem: PRIVATE_KEY_PEM
-  hosts:
-    - <%= ENV['BRAIN_DOMAIN'] %>
-    - <%= ENV['PREVIEW_DOMAIN'] %>
-  app_port: 8080
-  healthcheck:
-    path: /health
-
-registry:
-  server: ghcr.io
-  username: <%= ENV['REGISTRY_USERNAME'] %>
-  password:
-    - KAMAL_REGISTRY_PASSWORD
-
-builder:
-  arch: amd64
-
-env:
-  clear:
-    NODE_ENV: production
-  secret:
-    - AI_API_KEY
-    - GIT_SYNC_TOKEN
-    - MCP_AUTH_TOKEN
-    - DISCORD_BOT_TOKEN
-
-volumes:
-  - /opt/brain-data:/app/brain-data
-  - /opt/brain.yaml:/app/brain.yaml