@rizom/ops 0.2.0-alpha.13 → 0.2.0-alpha.130

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

@@ -1,384 +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 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
+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 get started.
+- **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.
 
-- 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
+## The way of working
 
-If we give you a **Bearer token**, treat it like a password. Do not share it.
+Rover is built around a simple loop:
 
-## One important idea: Discord is the default, MCP is optional
+**Capture → ask back → shape.**
 
-If you are new to Rover, 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
-- **Discord** is the default way most pilot users will talk to it
-- **MCP** is an optional direct connection method for supported AI clients
+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 unless we specifically ask you to use MCP.
+### Capture
 
-For most users, the practical meaning is simple:
+Notes for what's in your head:
 
-- join Discord
-- message Rover there
-- start using it
+> Save a note: I keep explaining the same idea to clients — maybe
+> it should be a workshop.
 
-If your cohort is also testing MCP, we will send the URL, Bearer token, and setup help separately.
+Links for what's on your screen:
 
-## What to use first
+> Save this link with my workshop idea — it's how someone else
+> structures theirs: https://example.com
 
-For most users, the easiest first setup is:
+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.
 
-- **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
+### Ask back
 
-## Default setup: Discord
+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:
 
-For most users, getting started means:
+> What have I added about the workshop idea?
 
-- join the Discord server we send you
-- open the Rover channel or DM
-- send a first message
+> What did I save this week?
 
-Try a first message like:
+And as material accumulates, the topics surface — the themes you
+keep returning to without noticing:
 
-> What can you help me do, and what should I use you for?
+> What themes do you see in what I've collected?
 
-Or:
+### Shape
 
-> Help me save my first note.
+When you want to make something from what you've gathered:
 
-If Discord is not enabled for you yet, tell us and we will share the right next step.
+> Turn my workshop notes into a one-page outline.
 
-## Optional: direct MCP access
+> Make a reading list from the links I saved.
 
-If we have asked you to use an MCP client, use one that supports:
+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.
 
-- **HTTP / Streamable HTTP MCP**
-- **Bearer token authentication**
+## When Rover can't do something: make a wish
 
-When your client asks for connection details, use:
+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:
 
-- **Server URL:** `https://<handle>.rizom.ai/mcp`
-- **Authentication type:** Bearer token
-- **Bearer token:** the token we sent you
+> I wish you could remind me about this next Monday.
 
-If the client asks for a name, use something simple like:
+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.
 
-- `Rover (<handle>)`
+## Your Rover in the network
 
-## Optional: Claude Desktop setup
+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.
 
-If we ask you to connect through Claude Desktop and your version supports a **remote HTTP / Streamable HTTP MCP server**, enter:
+**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:
 
-- **Server URL:** `https://<handle>.rizom.ai/mcp`
-- **Authentication:** Bearer token
-- **Token:** the token we sent you
+> Add yeehaa.io to my agents.
 
-Then try a first message like:
+Then ask questions that put their knowledge next to yours:
 
-> What can you help me do, and what should I use you for?
+> Ask yeehaa.io what they've published about designing workshops,
+> and compare it with my own workshop notes.
 
-Or:
+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:
 
-> Help me save my first note.
+> Save that comparison as a note with my workshop idea.
 
-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.
+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.
 
-## Your first 5 minutes
+**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.
 
-Once you are connected, try this sequence:
+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.
 
-### 1. Check that Rover responds
+## 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:
 
-> What can you help me do?
+- **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.
 
-### 2. Save a first note
+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
 
-> Save a note: I want to use Rover to collect ideas from my work, reading, and conversations.
+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.
 
-### 3. Save a useful link
+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.
 
-Ask:
+## If something doesn't work
 
-> Save this link and note why it matters to me: <paste URL>
+- **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.
 
-### 4. Ask Rover to reflect back what it knows
+## Tell us what you notice
 
-Ask:
+The feedback that helps most is small and honest — drop it in the
+Discord server as it occurs to you:
 
-> Based on what I’ve stored so far, what themes are starting to emerge?
+- 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
 
-### 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:
-
-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
-
-### 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 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. 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
-
-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 (default)
-
-Discord is the default interface for this pilot.
-
-Think of it as the main place to:
-
-- 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:
-
-- **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 yet, ask us and we will tell you whether your cohort is on the Discord-first workflow.
-
-## 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
-- 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.
-
-## 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 runs through Discord and, optionally, a direct MCP endpoint.
-
-### I got an authentication error in MCP
-
-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
-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>
-```
-
-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/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/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"
-		}
-	}
-}

package/templates/rover-pilot/deploy/Dockerfile

@@ -1,38 +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 gnupg debian-keyring debian-archive-keyring apt-transport-https \
-    && curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg \
-    && curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list \
-    && apt-get update && apt-get install -y --no-install-recommends caddy libcap2-bin \
-    && setcap cap_net_bind_service=+ep $(which caddy) \
-    && rm -rf /var/lib/apt/lists/*
-
-COPY deploy/Caddyfile /etc/caddy/Caddyfile
-
-RUN mkdir -p /srv/fallback && \
-    printf '<!doctype html><html><head><meta charset="utf-8"><title>brain</title></head><body></body></html>\n' \
-    > /srv/fallback/index.html
-
-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
-
-CMD ["sh", "-c", "caddy start --config /etc/caddy/Caddyfile && exec ./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