@rizom/ops 0.2.0-alpha.76 → 0.2.0-alpha.78

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

@@ -2,481 +2,316 @@
 
 Welcome to the Rover pilot.
 
-This guide is written for **first-time users**. You do **not** need prior experience with Rover, MCP, git, GitHub, or Obsidian 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, the normal experience is:
+For the current pilot, the normal core experience is:
 
-- **Discord** for chatting with Rover
-- the **Dashboard** in your browser at `https://<handle>.rizom.ai/`
-- the **CMS** in your browser at `https://<handle>.rizom.ai/cms`
+- **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
 
-Optional workflows exist too:
+Some users may also receive:
 
-- **MCP** for direct client access from supported AI tools
-- **git** if you want to work with the underlying files directly
-- **Obsidian** if you want a nicer note-focused editor for those same files
+- **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
 
-You can think of Rover as a private knowledge companion that helps you:
+If we did not explicitly give you CMS, GitHub, MCP, or Obsidian instructions, you can ignore those sections for now.
 
-- save notes
-- save links
-- reflect on your own material
-- find patterns in what you have collected
-- think through questions with AI
+## Start here: setup
 
-## The default mental model
+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 remember only one thing, remember this:
+## Your setup email
 
-- **Discord** = talk to Rover
-- **Dashboard** = browser overview
-- **CMS** = browser editing interface
-- **MCP** = optional direct client integration
-- **git / Obsidian** = optional file-based workflow
+The setup email contains a single-use passkey setup link.
 
-Most pilot users should start with the first three.
+Treat that link like a temporary password:
 
-## What you will receive from us
+- do not forward it
+- use it once
+- expect it to expire
+- ask us for help if it has expired or does not work
 
-We will send you the details you need to get started.
+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.
 
-That usually includes:
+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.
 
-- confirmation that Discord is enabled for you, plus the invite/setup steps
-- your **Dashboard URL**: `https://<handle>.rizom.ai/`
-- your **CMS URL**: `https://<handle>.rizom.ai/cms`
-- if you will use the CMS, an invite to your **private** Rover content repo plus instructions for creating a GitHub token
-- if needed, your Rover MCP URL: `https://<handle>.rizom.ai/mcp`
-- if needed, your **Bearer token**
-- any extra instructions if we are testing a specific workflow with your cohort
+## Your first Rover session
 
-If we give you a **Bearer token**, treat it like a password. Do not share it.
+Start in **Discord** if it is enabled for your pilot. That is the normal first interface.
 
-## Start here: your first 5 minutes
+### 1. Say hello
 
-For most users, the best first setup is:
+Send:
 
-1. join the Discord server we send you
-2. open your Dashboard at `https://<handle>.rizom.ai/`
-3. open the CMS at `https://<handle>.rizom.ai/cms`
-4. when the CMS asks for GitHub access, use a fine-grained GitHub token with access to your private Rover content repo
-5. send a first message in Discord and make one small edit in the CMS
+> What can you help me do, and what should I use you for?
 
-A simple first chat message is:
+Rover should answer with a short overview of what it can do.
 
-> What can you help me do, and what should I use you for?
+### 2. Create your first note
+
+Ask Rover to save a simple note:
+
+> Save a note: I am trying Rover because I want a better way to collect ideas, links, and questions in one place.
 
 Or:
 
 > Help me save my first note.
 
-A simple first CMS action is:
+### 3. Add your first link
 
-- open the **Notes** collection
-- create a short note about why you want to use Rover
-- save it
+Send Rover a link you want to remember:
 
-If Discord is not enabled for you yet, tell us and we will share the right next step.
+> Save this link and tell me why it might be useful later: https://example.com
 
-## One important idea: Discord + Dashboard + CMS are the default, MCP is optional
-
-If you are new to Rover, the shortest explanation is:
+Or:
 
-- **Rover** is the assistant
-- **Discord** is the default chat interface
-- the **Dashboard** is the default browser view
-- the **CMS** is the default browser editing interface
-- **MCP** is an optional direct connection method for supported AI clients
+> Add this as a link about tools I want to revisit: https://example.com
 
-You do not need to understand the protocol details unless we specifically ask you to use MCP.
+Rover should save the link and, when possible, keep a short description of why it matters.
 
-For most users, the practical meaning is simple:
+### 4. Upload an existing Markdown doc
 
-- join Discord
-- open your dashboard in the browser
-- use the CMS when you want to edit structured content directly
-- start using it
+If you already have notes or docs in Markdown, you do not need to retype them.
 
-If your cohort is also testing MCP, we will send the URL, Bearer token, and setup help separately.
+Upload a `.md` file and ask Rover to save or import it:
 
-## Working in the CMS
+> Save this Markdown doc in my notes.
 
-The CMS is the easiest way to edit Rover content in the browser.
+Or:
 
-Use it when you want to:
+> Import this doc and tell me what it is about.
 
-- create notes without touching git directly
-- edit existing content in a structured form
-- browse your collections in one place
-- make quick updates from the browser
+This is often the fastest way to give Rover useful context.
 
-### Why the CMS asks for GitHub access
+### 5. Ask Rover about what you just added
 
-Your Rover content lives in a **private GitHub repo**.
+After you have saved a note, link, or Markdown doc, ask Rover to reflect it back:
 
-The CMS edits that repo for you.
+> What have I added so far?
 
-That is why it asks for a **GitHub token**.
+Or:
 
-In practice, that means:
+> What do you know about what I am interested in so far?
 
-- you can use the CMS without cloning the repo locally
-- your changes still go into your private content repo
-- if you later open that repo with git or Obsidian, you are looking at the same underlying content
+This is the basic Rover loop: add material, then ask Rover to help you think with it.
 
-### What to expect the first time you open it
+### 6. Try a more useful task
 
-When you open `https://<handle>.rizom.ai/cms`, you should expect something like this:
+Once Rover has a little context, try one of these:
 
-1. the CMS asks you to authenticate with GitHub
-2. you enter the GitHub token we told you to create
-3. the CMS loads your content collections
-4. you can open an entry, edit it, and save your changes
+> Summarize my notes so far.
 
-If the CMS loads correctly, that is a good sign that:
+> What themes do you see in what I have added?
 
-- your browser access is working
-- your repo access is working
-- the token is working
+> Turn my rough note into a clearer paragraph.
 
-### What you will see in the CMS
+> Help me make a small reading list from the links I saved.
 
-The exact collections may change over time, but a normal pilot setup includes collections for things like:
+These examples show the main scope of Rover: saving material, organizing it, reflecting on it, and helping you make something from it.
 
-- **Notes**
-- links or saved resources
-- settings or other structured content
+### 7. Ask another agent
 
-The important idea is not the exact list — it is that the CMS is the browser-based editor for your Rover content.
+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 good first CMS task
+## The default mental model
 
-A good first CMS task is to create a short note.
+If you remember only one thing, remember this:
 
-For example:
+- **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
 
-- open **Notes**
-- create a new note
-- title it something like `Why I’m using Rover`
-- write 3 to 5 sentences
-- save it
+## What you will receive from us
 
-Then go back to Discord and ask Rover something like:
+Depending on your pilot cohort, we will send you some or all of these:
 
-> What do you know about why I’m using Rover so far?
+- 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
 
-That connects the browser editing workflow with the chat workflow.
+Keep setup links, GitHub tokens, and any MCP credentials separate. Do not paste the passkey setup link into an MCP client.
 
-### When to use Discord vs CMS
+## Discord
 
-A good rule of thumb is:
+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.
 
-Use **Discord** when you want to:
+Use it to:
 
-- think out loud
+- save quick notes
+- drop in links
 - ask questions
-- capture something quickly
-- use Rover as a day-to-day assistant
-
-Use the **CMS** when you want to:
-
-- deliberately create or revise content
-- browse existing entries
-- make cleaner edits than you would in chat
-- work in a more editor-like browser interface
+- use Rover day to day without setting up a separate client
 
-Use both together. That is the default pilot workflow.
+If Discord is enabled, we will send the exact invite/setup steps separately.
 
-### If the CMS feels confusing
+## Dashboard basics
 
-That is useful feedback.
+The Dashboard is the browser landing page for your Rover.
 
-Please tell us:
+Open it at:
 
-- what part was confusing
-- whether the problem was authentication, navigation, editing, or saving
-- what you expected to happen instead
+```text
+https://<handle>.rizom.ai/
+```
 
-We want to improve this workflow.
+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.
 
-## Optional: direct MCP access
+## Optional: Working in the CMS
 
-If we have asked you to use an MCP client, use one that supports:
+If CMS is enabled for you, open:
 
-- **HTTP / Streamable HTTP MCP**
-- **Bearer token authentication**
+```text
+https://<handle>.rizom.ai/cms
+```
 
-When your client asks for connection details, use:
+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.
 
-- **Server URL:** `https://<handle>.rizom.ai/mcp`
-- **Authentication type:** Bearer token
-- **Bearer token:** the token we sent you
+Use the CMS when you want to:
 
-If the client asks for a name, use something simple like:
+- create or edit notes in the browser
+- add existing Markdown docs
+- browse structured content collections
+- make cleaner edits than you would in chat
 
-- `Rover (<handle>)`
+A good first CMS task is:
 
-## Optional: Claude Desktop setup
+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
 
-If we ask you to connect through Claude Desktop and your version supports a **remote HTTP / Streamable HTTP MCP server**, enter:
+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.
 
-- **Server URL:** `https://<handle>.rizom.ai/mcp`
-- **Authentication:** Bearer token
-- **Token:** the token we sent you
+## Optional: direct MCP access
 
-Then try a first message like:
+MCP is an optional way to connect Rover directly to an AI client that supports remote HTTP MCP.
 
-> What can you help me do, and what should I use you for?
+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.
 
-Or:
+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.
 
-> Help me save my first note.
+### What the MCP login flow looks like
 
-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.
+If your client supports OAuth / browser login, the normal flow is:
 
-## Optional: git, text files, and Obsidian
+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 underlying content workflow is still a normal **git repo** with normal **markdown/text files**.
+You should not need to copy a setup link into the client. The setup link is only for registering your first passkey.
 
-But for this pilot, treat that as **optional**.
+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.
 
-Use direct git or file-based workflows only if you want more control.
+### Client-specific notes
 
-Obsidian is optional. It is just one possible editor for those files.
+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.
 
-That means:
+### If MCP does not work
 
-- use **Discord** as the main way to talk to Rover
-- use the **Dashboard** and **CMS** as the normal browser workflow
-- use a normal editor plus **git** only 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
+Send us:
 
-### Important: your content repo is private
+- the client name
+- the client version
+- the exact error message
+- a screenshot if possible
+- the server URL you entered, without any secret token
 
-If you use the git/text-file workflow, you will be working in your own **private** GitHub repo.
+Do not paste your passkey setup link into an MCP client.
 
-That means:
+## Optional: git, text files, and Obsidian
 
-- you do **not** need repo access just to use Rover in Discord
-- 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
+Rover content can also live as normal markdown/text files in a private GitHub repo.
 
-### How you get access
+This workflow is optional. Use it only if we explicitly enabled it for you or if you want more control.
 
-If you want the git/text-file workflow, we will:
+If enabled, 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
-
-### Authentication options
-
-To work with a private repo or the CMS, you need GitHub authentication.
-
-Usually the easiest order is:
-
-1. **GitHub sign-in** to accept the private repo invite
-2. a **fine-grained personal access token** for the CMS, with access to your private Rover content repo
-3. **GitHub Desktop** or normal git auth if you also want to clone the repo locally
-4. **SSH key** only if you already use git that way
-
-You do **not** need a GitHub token just to use Rover in Discord.
-You do **not** need an MCP Bearer token unless we explicitly ask you to use MCP.
-
-### If you want the local file workflow
-
-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 and the CMS. If we have also asked you to test MCP, you can use that too.
-
-## Discord (default chat interface)
-
-Discord is the default chat interface for this pilot.
-
-Think of it as the main place to:
+3. send you the repo URL
+4. explain whether to use GitHub Desktop, command-line git, Obsidian, or the CMS
 
-- 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 chat interface**
-- the **Dashboard** and **CMS** are the main browser interfaces
-- 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.
-
-## Dashboard basics
-
-The Dashboard is the browser landing page for your Rover.
-
-Use it when you want to:
-
-- confirm the instance is up
-- see the browser-side operator surface
-- jump into the CMS quickly
-
-This is not meant to be a public website. It is part of your Rover control surface.
+You do not need GitHub repo access just to use Rover in Discord.
 
 ## Wishlist: when Rover cannot do something yet
 
-Rover has a built-in **wishlist**.
-
-This matters 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.
+Rover has a built-in wishlist.
 
-### 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.
+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
-- if you are using MCP, access to `/mcp` is protected by your Bearer token
-- your content repo is private
-- 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 public site
-
-That is expected. The root URL is your **Dashboard**, not a public website. The CMS lives at `/cms`. Rover also runs through Discord and, optionally, a direct MCP endpoint.
-
-### The CMS asks for GitHub auth and I am not sure what to do
-
-That is expected.
-
-Use the GitHub token we told you to create for your **private Rover content repo**.
+### I did not receive the setup email
 
-If you are missing one of these pieces, tell us:
+Check spam/promotions first. If it is not there, tell us which email address we should use.
 
-- you did not get the repo invite
-- you did not accept the repo invite yet
-- you are not sure how to create the token
-- the token was accepted but the CMS still does not load
+### The setup link expired or does not work
 
-### The CMS loads, but I am not sure whether my change worked
+Reply to your Rover operator. We can rotate/reissue setup.
 
-A good quick test is:
-
-1. edit a short note in the CMS
-2. save it
-3. refresh the CMS and confirm the change is still there
-4. ask Rover in Discord about that note
-
-If anything in that loop feels unclear, tell us exactly where it became confusing.
-
-### I got an authentication error in MCP
+### I opened the domain and it does not look like a normal public site
 
-Usually this means one of three things:
+That is expected. The root URL is your Dashboard, not a public marketing site.
 
-- the Bearer token was missing
-- the Bearer token was pasted incorrectly
-- the client is using the wrong authentication type
+### The browser asks me to use a passkey
 
-Double-check that you are using:
+That is expected after setup. Use the same passkey you registered from the setup email.
 
-- URL: `https://<handle>.rizom.ai/mcp`
-- auth type: **Bearer token**
-- token: exactly the token we sent you
+### My MCP client cannot connect
 
-### My MCP client says it cannot connect
+Send us the client name, version, exact error message, and a screenshot if possible.
 
-Some clients support local MCP servers better than remote HTTP MCP servers.
+### The CMS asks for GitHub auth and I am not sure what to do
 
-If that happens, send us:
-
-- the name of the client
-- the version you are using
-- the exact error message
-- a screenshot if possible
+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 Discord, Dashboard, and CMS each made sense
+- 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
@@ -489,17 +324,16 @@ Short, honest feedback is perfect.
 When we onboard you, the message will look roughly like this:
 
 ```text
+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>
-Dashboard URL: https://<handle>.rizom.ai/
-CMS URL: https://<handle>.rizom.ai/cms
-CMS auth: GitHub token with access to your private Rover content repo
 MCP access: optional / enabled / not enabled
-
-If MCP is enabled:
-MCP URL: https://<handle>.rizom.ai/mcp
-Auth type: Bearer token
-Bearer token: <token>
+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.