User journeys

How the people who use rolter get from “I have a job to do” to “it is done”, written as scripts: one per person and goal, step by step, with the branches a real deployment takes. They exist for three reasons at once:

• Planning. Each script describes the journey as it should go. Where the product does not support a step yet, the step says so and links the issue, so the gaps read as a list in the gap register instead of being rediscovered by every new user.
• Testing. The scripts are what the pre-1.0 live pass (#1789) walks, on the dogfooding fleet: headless by an agent driving the dashboard in Chromium plus the API, and by a real person while an observer watches the telemetry. See running a script.
• Onboarding. The steps that already work end to end are also the public guides, minus the gap tracking.

The user-facing docs describe features; these describe people. When the two disagree about what a person can do, one of them is wrong — file it.

The people

rolter has three scoped roles — viewer, member, admin — granted at an org, a team or a project, plus the deployment-wide superadmin (the admin token, or an account with the superadmin bit). Custom roles and access profiles can only widen a scoped role (see RBAC & auth). Every persona below is one of those, at one scope:

SecOps and DevOps are superadmin today only because nothing narrower reaches the deployment-wide settings they need. Both scripts start from that and mark it as the first gap.

The simplest paths

Most people only ever need one of these. Every longer script is a branch off one of them.

1. Five minutes, no credentials. rolter easy-up, open the dashboard and send a Playground message to the built-in fake-llm model. Proves the gateway and the dashboard before a single provider key exists. Add --clickhouse-url pointing at a ClickHouse that has rolter’s schema (clickhouse/*.sql) and LLM Logs shows the row too, which proves the log pipeline. (platform-admin A0-a)
2. One hour to a team deployment. Install with Postgres, Redis and ClickHouse, sign in as the seeded admin, follow the dashboard’s Getting started card — connect a provider, add a route, mint a key — and hand people either an invitation or single sign-on. (platform-admin A0-c to A4)
3. Configuration as code. Keep providers, groups, routes, prices and prompt templates in a rolter.toml, apply it with rolter-seed --import (desired state), and read the live state back with rolter config export. What the file cannot carry — keys, budgets, SSO, policy — stays in the dashboard or the API. (platform-admin A3-d)
4. An engineer’s first call. Sign in, Settings → My Virtual Keys → Generate virtual key, point the OpenAI or Anthropic SDK (or a coding agent) at the gateway with that key. (engineer E1–E4) Until #1846, the dashboard half works only for someone who also holds a role at the org: an invitation to a project grants nothing above it.

How to read a script

Each script is a table of steps. A step names what the person does, where they do it — the dashboard path first, the API equivalent second, so the same step can be run by hand, by a browser driver or by curl — what they should see, and its status:

Where the path forks — no identity provider or OIDC, one model or a fleet — the script names the fork, the question that decides it, and gives each branch its own steps (A1-a, A1-b, …). A branch is walked in a run only when the run is testing that branch; the rest are still read, because a branch nobody walks rots.

Dogfood data

Every script runs against the stack just dogfood brings up (the dogfooding fleet). Seed the fleet and the personas once:

just dogfood                                    # the stack, SigNoz, the sheet
just dogfood-seed                               # 15 fake providers, 3 groups, 11 routes
just dogfood-personas                           # one account per persona

personas.sh is idempotent and prints the roster. Every account shares the dogfood password from integration/dogfood/creds.env:

The fleet lives in project default/default: routes gpt-4o, gpt-4o-mini, claude-sonnet-4, llama-3.1-8b (round robin), llama-3.1-8b-cached (cache-aware), llama-3.1-8b-fastest, qwen-32b (power of two), mistral-7b (predicted latency), gemma-27b (weighted), deepseek-r1 (adaptive) and text-embedding, plus group addresses such as vllm-a100/…. Three targets are bad on purpose — vllm-a100-03 is slow, vllm-spot-01 answers 503 a quarter of the time, vllm-spot-02 takes 1.4 s to first token — so failure, retry and latency screens have something to show. research/sandbox has no routes; it exists so one project’s people can be shown not seeing another’s traffic.

Running a script

Headless — an agent drives it

This is how a script runs when nobody can open the dashboard: the stack is in a cloud container, or the run is a regression pass.

1. Bring the stack up and seed it (above). Mint nothing by hand: every key and account a script needs is made by its own steps or by personas.sh.
2. Walk the steps as the persona. Dashboard steps are driven in headless Chromium (Playwright) signed in as the persona’s account — a screenshot of each step’s end state is kept, because “the button was there” is not the same claim as “the button was usable”. API steps use curl with the persona’s session (POST /api/v1/auth/login) or the virtual key the script minted.
3. Check every Expect against the source of truth rather than the screen: the API’s answer, a request_logs row in ClickHouse, an audit_log row in Postgres.
4. Record the result per step in the run log. A failed step is either a bug in rolter (file it), a wrong script (fix the script in the same PR as the run log), or a known gap (already linked).

just dogfood-journeys does steps 2 and 3 for every script: one runner per persona in integration/dogfood/journeys/, results and screenshots in integration/dogfood/.journeys/, and a summary.md to copy into the run log. just dogfood-screens adds the persona × screen matrix. See walking it as someone else. A runner step and its script step share an id; when a script changes, change its runner in the same PR.

Watched — a person drives it, an observer watches

This is the #1789 pass: someone who did not build the screen uses it, and the struggle is the finding.

1. The person runs the stack locally (just dogfood) or on a shared host and signs in as the persona. They get the script’s goal, not its steps — the steps are what the observer checks them against.
2. The observer runs just dogfood-watch (live ui_events and gateway traffic), keeps SigNoz open on rolter · dashboard UX, and notes every place the person hesitates, backs out, reaches for a refused control (refused_click) or abandons a form (form_abandon).
3. Afterwards the two walk the script together and mark each step. A step the person completed by a route the script did not foresee is a finding too: the script, or the screen, is wrong about how people think.

What the observer watches

Run log

Add a row per run. The full walk of every script is the #1789 pass.

Gap register

Every step marked partial, gap or bug, in one place. Milestones and priorities live on the issues.

Public guides

The paths that already work end to end are published as user-facing guides in docs/user-docs/guides/, without the gap tracking: the admin’s first hour, connecting models, an engineer’s first call, and tracking spend. When a gap here closes, the matching guide gains the step.