@rizom/ops 0.2.0-alpha.28 → 0.2.0-alpha.281

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

@@ -1,384 +1,90 @@
-# Rover Pilot User Onboarding
+# Welcome to your brain
 
-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
+Your brain is a private space where that thinking accumulates — notes, links, fragments, and half-formed ideas — plus an AI that can work with all of it. It can find things you saved months ago, connect topics, or help turn a rough note into a draft. The more useful material you add, the more useful it becomes.
 
-Rover is your private AI assistant for working with your own notes, links, and ideas.
+---
 
-In this pilot, Rover is intentionally simple:
+## What it is
 
-- 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
+Your brain is a private knowledge companion. It holds your notes, links, and ideas and helps you think with them, not just store them.
 
-You can think of Rover as a private knowledge companion that helps you:
+Ask a question and it searches what you've saved. Give it a fragment of thinking and it can help develop it.
 
-- save notes
-- save links
-- reflect on your own material
-- find patterns in what you have collected
-- think through questions with AI
+## Getting in
 
-## What you will receive from us
+We'll send you a personal URL such as `https://<handle>.rizom.ai/`.
 
-We will send you the details you need to get started.
+The first time you open it, you will be asked to set a passkey. No password is required after that.
 
-That usually includes:
+Your main interfaces are:
 
-- 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
+- **Chat** (`/chat`) — talk to your brain;
+- **Dashboard/site** (`/`) — the configured browser surface;
+- **CMS** (`/cms`) — edit durable content in a browser.
 
-If we give you a **Bearer token**, treat it like a password. Do not share it.
+Start with Chat.
 
-## One important idea: Discord is the default, MCP is optional
+## Your first five minutes
 
-If you are new to Rover, the shortest explanation is:
+1. Open Chat and say: _Help me save my first note._
+2. Save a thought, link, or idea. It does not need to be polished.
+3. Ask about it and inspect what comes back.
 
-- **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
+That save–ask–use loop is the core workflow.
 
-You do not need to understand the protocol details unless we specifically ask you to use MCP.
+## Chat or CMS?
 
-For most users, the practical meaning is simple:
+**Chat** is for thinking aloud, asking questions, saving things quickly, and day-to-day work.
 
-- join Discord
-- message Rover there
-- start using it
+**CMS** is for deliberate browsing and editing. It becomes more useful as your content grows.
 
-If your cohort is also testing MCP, we will send the URL, Bearer token, and setup help separately.
+## Other interfaces and peer brains
 
-## What to use first
+Chat is primary. Your configured posture may also enable Discord, Slack, MCP clients, or agent-to-agent calls. We will send setup steps for integrations enabled for your instance.
 
-For most users, the easiest first setup is:
+With permission, you can save another participant's brain as a contact and call it by its shared address:
 
-- **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
+- _Add jane.rizom.ai to my contacts._
+- _Call jane.rizom.ai and ask [your question]._
 
-## Default setup: Discord
+## Connecting other tools
 
-For most users, getting started means:
+MCP is a standard protocol that lets compatible AI clients use your brain's tools and lets configured integrations connect to external services. If MCP is part of your setup, we will send specific instructions alongside your URL.
 
-- join the Discord server we send you
-- open the Rover channel or DM
-- send a first message
+## Common questions
 
-Try a first message like:
+**How do I access my data?**
 
-> What can you help me do, and what should I use you for?
+Use the CMS. If your cohort includes GitHub access, the same durable markdown also lives in a private repository.
 
-Or:
+**Does it search the public internet?**
 
-> Help me save my first note.
+Not by default. Answers are grounded in your own knowledge unless an explicitly configured integration provides another source.
 
-If Discord is not enabled for you yet, tell us and we will share the right next step.
+**What does this cost?**
 
-## Optional: direct MCP access
+Nothing during the pilot; hosting is covered by the programme.
 
-If we have asked you to use an MCP client, use one that supports:
+## This is a pilot
 
-- **HTTP / Streamable HTTP MCP**
-- **Bearer token authentication**
+The product works, but it is not finished. You will encounter rough edges and missing behavior. If something breaks or falls short, tell us what you tried, what you expected, and what happened.
 
-When your client asks for connection details, use:
+A built-in wishlist can record unsupported requests as product feedback.
 
-- **Server URL:** `https://<handle>.rizom.ai/mcp`
-- **Authentication type:** Bearer token
-- **Bearer token:** the token we sent you
+## Your access details
 
-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:
-
-> 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:
-
-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:
+We will send details in this shape:
 
 ```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>
+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 if enabled
+MCP: enabled/not enabled — setup details 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 see and we will help.

package/templates/rover-pilot/pilot.yaml

@@ -1,11 +1,10 @@
-schemaVersion: 1
 brainVersion: 0.1.1-alpha.14
-model: rover
 githubOrg: <github-org>
 contentRepoPrefix: rover-
 domainSuffix: .rizom.ai
-preset: core
+bundles:
+  - 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