# Walk the guides in the cloud

ShipVitals' cloud can walk your project's how-to guides step by step in a real browser, as a careful reader would, against your staging site, and report what doesn't match. It's paid with your workspace's AI credits, so you need no model key and no machine of your own. Findings aren't coverage: a walk finds some defects and proves nothing about the rest.

To walk on your own machine with your own OpenRouter key, against localhost, see [Walk the guides](walk-the-guides.md).

## Before you start

- **Guides the walker can read:** Markdown with numbered steps, either in the `docs/how-to` folder of the project's one bound GitHub repository, or on a docs page on one of the project's web surfaces.
- **A staging site** as one of the project's web surfaces (see [Projects](projects.md#surfaces)). The cloud walker opens only an `https://` host whose name says it's a test environment, with a label such as `staging`, `stage`, `dev`, `test`, `qa`, `sandbox` or `preview` (`staging.example.com`, `qa-2.example.com`). Your live site is never walked.
- **AI credits** left this month. **Plan & billing** shows them.
- **To start a walk**, you must be able to run the project's checks. To add a test persona, you must edit the project.

## Open the sheet

1. Open the project, then its **Health** tab, and find **Browser checks**. Where ShipVitals is run without browser checks and none were added before, Health has no **Browser checks** section, so there's no **Walk the guides**: walk on your own machine instead (see [Walk the guides](walk-the-guides.md)).
2. Press **Walk the guides**. The sheet says **Walk the guides** and "ShipVitals' cloud walks your how-to guides step by step in a real browser, as a careful reader would, with your workspace's AI credits. …" While it reads the project it says "Reading what this project can walk…".

If you can't start walks on the project, the sheet says "Only people who run this project's checks can start a walk."

## Add a test persona

A test persona is a test account on one of your staging sites that the walker signs in as. Add one before the first walk that needs a signed-in user.

1. Under **Target**, choose the staging site the persona signs in to. A persona belongs to that target: its password is typed there and nowhere else, and it's offered under **Test persona** only while that target is chosen.
2. In the sheet, under **Add a test persona**, fill in:
   - **Name**, such as "Test Owner".
   - **Role**, such as "owner".
   - **Email**: "On a test domain, such as owner@example.test." Only reserved test domains are taken (`.test`, `.example`, `.invalid`, `.localhost`, `example.com`, `example.net`, `example.org`), so a real account is never used.
   - **Password**.
3. Press **Save persona** (or `Enter` in any of its fields). It's chosen under **Test persona** at once.

"A test account on this target, used there only. Its password is stored encrypted and never shown again; the model never sees it." ShipVitals types the password for the walker. A persona stays with the project until the project is deleted.

If it isn't saved, the sheet says "The persona wasn't saved. Its email must be on a test domain, and its name new to this target."

## Choose what to walk

1. Under **Guides from**, choose where the guides come from:
   - **The repository (owner/repo), docs/how-to**: the guides are read at once from the repository through ShipVitals' GitHub App.
   - **A docs page on the project's site**: type its address under **Docs page** ("A Markdown guide, or a page whose numbered lists are its steps, on one of the project's web surfaces."), then press **Read the guides** (or `Enter`).

   Without one bound GitHub repository, only the docs page is offered, and the sheet says "Bind one GitHub repository to this project to walk its docs/how-to guides, or use a docs page."
2. The sheet says "Reading…", then lists them under **Guides**, each with its title and its number of steps ("Sign in · 6 steps"). Untick any you don't want walked. A walk takes at most 10 guides: with more ticked, the sheet says "A walk takes at most 10 guides. Untick some to start." and **Start walk** waits until you do.
3. Under **Target**, choose the staging site. Only the project's web surfaces that are test environments are listed.
4. Under **Test persona**, choose a persona added for that target, shown as "Test Owner (owner)", or **Signed out**.
5. Set **Spending limit (credits)**: 200 to start with (or what you have left, if less), at most 5,000. "At the limit the walk stops at the end of the step it's on, and reports what it covered."

## Read the estimate and start

1. Above **Start walk**, read the estimate and the origin rule, for example:
   - "About 60 credits for 3 guides (24 steps). You have 162 left this month."
   - "Only pages on staging.example.com are opened."
2. Press **Start walk**. It says **Starting…**, then the walk's run page opens.

The estimate comes from the guides' steps; the walk itself is charged what each model call actually cost, and never more than its limit.

## Watch it

The run page says **Walking** and the project's name, with **All runs** above it to go back.

- Under the title: "Starting the walk…", then "Walking…".
- What's spent: "12 of 200 credits · The walker can open only https://staging.example.com."
- Each guide as a checklist. Each step is **Waiting**, then **Pass**, **Fail**, **Warn**, **Blocked** or **Unwalked**, with the guide's words and the walker's note under it, quoted.
- **The current step**: a screenshot of what the walker sees ("No screenshot yet." before the first).
- When the walker's browser asked for anything outside the target: "The walk's guard stopped 3 requests outside https://staging.example.com."

The page reads the walk again every few seconds while it runs.

### Stop it

Press **Stop**. It says **Stopping…**. The walk ends before its next model call, and only the steps it took are charged. If it doesn't stop, the page says "The walk didn't stop. Try again."

## Read the findings

When the walk ends, the title says **Walked** and the project's name, and the line under it says how it ended:

- "The walk finished."
- "The walk stopped at its credit limit, at the end of the step it was on. What it didn't reach is Unwalked."
- "The walk was stopped. Only the steps it took were charged; what it didn't reach is Unwalked."
- "The walk ended with an error: …"

**Findings** lists what the walk found, or says "Nothing was found." "Quoted as the walker wrote it: a page or a guide can say anything."

Each finding shows its id, its severity (**S1 Blocker**, **S2 Major**, **S3 Minor** or **S4 Cosmetic**), **Confirmed** or **Observed once**, and "Sign in · step 4", then its title, **Expected** and **What happened**. **Confirmed** means it happened again from a fresh start; **Observed once** means it didn't. Confirmed ones are listed first.

Confirmed findings are kept with the project, so they show on its release gate (see [The release gate](release-gate.md)).

### Open a GitHub issue

With one GitHub repository bound to the project, each finding has **Open a GitHub issue**, which opens a new issue on it, filled in.

- If the repository is public, or ShipVitals can't tell, it says so first ("… is a public repository: anyone can read this issue, with the finding's text and evidence names."). Press **Open the issue** to go on.
- A finding too long for the link is put on your clipboard: "The finding was too long for the link, so it's on your clipboard. Paste it into the issue's description."

Without a bound repository, the page says "Bind one GitHub repository to this project to file issues from here."

## Download the report

Press **Download report for qa-repair**. It saves `QA_REPORT_<YYYYMMDD-HHMM>.md`, in the format the `qa-repair` skill reads. **Download report for qa-repair** appears when the walk ends. If the walk ended without a report, the page says "The report is written when the walk ends."

## When the credits run out

A walk needs AI credits left this month. When they're used, **Start walk** answers "Your workspace has used this month's AI credits. They come back on Dec 1, or add a pack in Plan & billing." Only the workspace owner can add a pack. Owners and admins get a notice in the bell as the month's credits run low.

A walk that reaches its own limit stops at the end of the step it's on, and reports what it covered. Raise **Spending limit (credits)** next time to walk further.

Walking on your own machine with your own OpenRouter key uses no credits: see [Walk the guides](walk-the-guides.md).

## From the command line

In a linked folder signed in to the workspace (see [The vitals command line](vitals-cli.md)):

```
vitals walk --cloud
```

It starts a cloud walk of the project's guides, from its repository, on its first staging target, as the first test persona added for that target, with a limit of 200 credits (or what's left, if less). It says "Walking 3 guides in ShipVitals' cloud on https://staging.example.com as Test Owner, limit 200 credits (840 left this month).", "Only pages on staging.example.com are opened. Follow it at …", then prints each step as it's marked:

```
  ✓ sign-in · 1  Open the sign-in page
  ✗ sign-in · 2  Press Continue
```

When it ends it prints how it ended, "1 finding confirmed · 48 of 200 credits", and "Saved QA_REPORT_….md for qa-repair." into the folder.

- `--guide <slug>` walks only that guide; give it more than once for several. A walk takes at most 10 guides, so with more in the repository it says "A cloud walk takes at most 10 guides and this source has 14: name them with --guide." and doesn't start.
- `--persona <name>` walks as that persona; `--target <address>` on that staging target. A persona signs in only to the target it was added for: one added for another target says "That persona signs in to another test environment: pass its --target."
- `--limit <credits>` sets the spending limit.
- `--docs <url>` reads the guides from a docs page instead of the repository.
- `--no-save` doesn't save the report.
- Ctrl-C stops the walk before its next turn, and it still reports what it covered.

It exits `0` when the walk finished with nothing found, `1` when it found something, and `2` when it stopped short. It exits `3` when the walk didn't start because of a wrong option or a refusal (`2` when the credits are used).

## When it doesn't work

| The sheet says | What to do |
|---|---|
| "Add the project's staging site as a web surface first: …" | Add the staging site to the project's surfaces (see [Projects](projects.md#surfaces)). |
| "The walker opens a test environment from the project's web surfaces, such as staging." | Choose a **Target** whose host name says it's staging. |
| "No guides the walker can read: Markdown with numbered steps." | Add guides with numbered steps to `docs/how-to`, or choose another docs page. |
| "Choose at least one guide." | Tick a guide under **Guides**. |
| "The project has no one GitHub repository to read guides from." | Bind one GitHub repository to the project, or use a docs page. |
| "GitHub didn't let ShipVitals read the guides. Try again." | Check that ShipVitals' GitHub App can still read the repository, then try again. |
| "The docs page must be on one of the project's web surfaces." | Use a page on one of the project's sites. |
| "That docs page didn't load as Markdown or a web page." | Check the address. |
| "That persona isn't on this project any more." | Choose another persona, or add it again. |
| "That persona signs in to another test environment. Pick one added for this target." | Choose a persona added for this **Target**, or add one for it. |
| "Your workspace has used this month's AI credits. …" | Wait for the date it names, or have the workspace owner add a pack in **Plan & billing**. |
| "Too many walks started. Try again in a minute." | Wait a minute. |
| "The guides were read too often. Try again in a minute." | Wait a minute before reading the guides again. |
| "Guide walks don't run on this deployment." | Walk on your own machine: see [Walk the guides](walk-the-guides.md). |
| "The walk didn't start. Try again." | If more than 10 guides are ticked, untick some. Otherwise press **Start walk** again. |
| "The walk's board didn't load." | Reload the run page. |
| "The report didn't download. Try again." | Press **Download report for qa-repair** again. |
