# Using the dashboard

**At the end:** the dashboard open in your browser, and you able to find a run,
answer what it's waiting on, and stop it.

## Before you start

- Loadout installed and a project registered. See [your first run](first-run.md).
- A team run to look at, or the intention to start one. See
  [running a team](teams.md).
- A browser on the same machine.

## Steps

### 1. Start the dashboard

```sh
loadout dashboard
```

You should see the address it's serving on printed in the terminal. It's a
loopback address — only this machine can reach it — and it carries a token that
changes every time the dashboard starts, so an old link stops working.

If a Loadout daemon is already serving a dashboard, this command prints the
daemon's address instead and starts nothing, so you don't end up with two pages
over the same runs.

A team you start from this page runs inside this command, so it stops when you
close the terminal. The page tells you so above the form.

### 2. Open the address

Copy the whole address, token included, into your browser. Or start it with
`--open` to have it opened for you:

```sh
loadout dashboard --open
```

![The dashboard's run list. A band of totals across the top, the Needs you rail, and the screens as a row of tabs. Then one run under "Needs you", whose card shows the question it is asking, one under "Running", and two under "Finished". Each card names its team and room and states its state as a word, with a glyph beside it.](../images/dashboard-list-rich.png)

You should see a band of totals across the top, then your runs grouped under
*Needs you*, *Running* and *Finished*. *Needs you* comes first because a run
waiting on you is the one most likely to be missed further down.

### 3. Choose plain or rich

Which page you get follows your accessibility profile. Under the
`screen-reader` or `low-vision` preset, or with colour set to none, you get the
plain page; otherwise the rich one. To choose for this start only:

```sh
loadout dashboard --view plain
```

![The plain dashboard: the same four runs as a single list, each row giving the run's name, its state in words, and what it has cost.](../images/dashboard-list-plain.png)

You can also press **Plain view** in the top bar of either page. It's early
in the tab order on purpose. `--view` doesn't override your motion setting:
asking for the rich page isn't asking for more movement.

### 4. Move between the screens

Across the top of the runs pane are five screens. The first four show the same
runs in different ways, and *Terminal* shows what a node is doing now. What
hasn't become a run yet, the schedules and the open tasks, waits in the
office's lobby.

- **List** — dense and complete. The default.
- **Office** — the runs as a building, teams sharing its floors and a desk per
  node. The one to leave on a spare screen. Click a floor to go in and see
  everybody on it, square on or from a corner; [the office](../office.md)
  explains the rest.

  ![The office screen. The building from its corner in pixel art, isometric: ten floors of blue glass, LOADOUT on the roof, the first floor lit warm where its two teams sit, among the neighbourhood's brick and glass blocks, parks and roads. Along the top, the views - corner, aerial, from the street, the lobby - and the buttons to turn and zoom.](../images/dashboard-office.png)

- **Graph** — who asked whom. Reach for it when something is stuck.

  ![The graph screen. The lead's card at the top, with lines to the cards of the two workers it asked for. Each card gives the node's name, role and cost, and its state as a word; one is marked "waiting for you" and joined by a dashed amber line.](../images/dashboard-graph.png)

- **Timeline** — where the time and money went, a strip per day.

  ![The timeline screen. Two days, each a single track with a bar for every run, runs that overlapped on lanes of their own, and the day's runs, time and cost beside it. A running run's bar is striped and a finished one is solid.](../images/dashboard-timeline.png)

- **Terminal** — a node's output, line by line, as it happens.

None of these screens can change anything. Every control lives in the detail
pane, so answering a gate is built once rather than several times.

Each screen has its own place in the address - `#office`, `#graph`, `#when`,
`#waiting`, `#terminal` - so you can bookmark one, and Back takes you to the
screen you were on before. Choosing a screen moves the keyboard focus to its
heading, which is also what a screen reader reads out.

### 5. Open a run and answer a gate

Select a run. It opens in the detail pane.

![A run open in the detail pane, beside the list. Its heading with its state and facts, a gate asking whether to open a pull request with Approve and Refuse buttons, its three done-when criteria, two marked met and one not attempted, and what it has spent against its budget.](../images/dashboard-run-detail.png)

You should see its done-when criteria, each marked met, unmet or not attempted
in words, and any gate it's waiting on. A gate is a point where the run stops
and asks you before going on. Press **Approve** or **Refuse**.

Once the lead has reported, the goal is shown with what the lead took it to
mean, and each criterion with a **Taken to mean** line under it. Read the two
side by side: a run working hard on a nearby, easier goal looks on track until
you do.

A question from the lead has one more button than its options: **Think again**.
Use it when none of the options is right. The lead is told none was chosen, and
decides the thing itself or asks a better question.

The button runs the same command you could type yourself:

```sh
loadout team gate
```

That prints what the run is waiting on and how to answer it.

### 6. Start a team from the page

Press the button to start a team.

![The form for starting a team run. A team chosen, the goal typed in, and three done-when criteria, one per line.](../images/dashboard-start-form.png)

Choose a team, type the goal in your own words, and put one done-when criterion
per line. Criteria are one per line rather than comma-separated because a
criterion is a sentence, and sentences contain commas.

If the team has criteria of its own, the empty box shows them, and the run is
held to them unless you write your own — yours replace the team's.

**Take the lead's recommendation after** is for a run you won't be watching.
Put `30m` or `2h` and any question of the lead's that nobody answers in that
time takes its recommendation. Leave it empty and questions wait for you.

### 7. Stop or hold a run

From the detail pane, stop or hold the run. From a terminal it's:

```sh
loadout team halt --pause    # hold it before its next round
loadout team halt --resume
loadout team halt            # stop it after the round it is in
```

### 8. Change the look, if you want to

Open the settings page.

![The dashboard settings in the light High contrast theme: black on white with every rule drawn, High contrast and Light chosen, and the five accents each with a swatch beside its name.](../images/dashboard-themes.png)

These change how this browser draws the page, and stay in this browser and
nowhere else.

- **Theme.** Graphite, the default, is dark; Daylight is its light
  equal; Carbon is true black, for an OLED screen or a spare monitor at night,
  and is dark only; High contrast has a dark and a light, with every word at
  7:1 or better and every rule drawn.
- **Light or dark.** Follow your system, which is the default, or pick one.
  It chooses between Graphite and Daylight, and between the two high-contrast
  themes.
- **Accent.** Bay, Signal, Orchid, Sand or Frost: the colour of what you can
  act on and where you are. A set rather than a colour picker, because each
  was measured in every theme.
- **Density.** Compact, Comfortable or Spacious.
- **Text size.** 100%, 112%, 125% or 150%. Everything grows with it, controls
  included, and your browser's zoom still works on top.
- **Reading.** Roomy spaces lines, letters and words further apart, and stops
  a run's goal being cut short on its card.
- **Focus ring.** Bold draws the ring round whatever the keyboard is on at 3
  pixels rather than 2. The high-contrast themes always draw it bold.
- **Movement.** As your profile and system say, or none at all. Your machine
  is asked as well and the quieter answer wins, so nothing here can bring back
  movement you turned down elsewhere.

A look chosen before this version, in the old Paper, Slate or Oxblood themes,
comes back as Graphite; High contrast stays High contrast; and every old accent
becomes Bay.

### 9. Work on your ideas

Open the **Ideas** tab. Like the settings, it's a page of its own rather than
a way of looking at the runs, so the run pane's heading and forms are put away
while you're on it. The number on the tab is how many ideas are waiting on
your answers.

- **Drop an idea in** keeps what you write, on a project or the workspace-wide
  list. Nothing happens to it until you refine it.
- **Dump notes kept elsewhere** takes notes pasted from anywhere. An agent
  splits them into separate ideas and tasks, each quoting its own words from
  the notes, and they turn up on the page ticked. Untick what you don't want
  and record the rest.
- Each idea opens to show its questions, then the plan. Answer a question by
  picking one of the agent's likely answers (the recommended one is first) or
  in your own words. Choose an option for each layer, keep or drop pieces,
  ask for a piece or the whole plan to be reworked, and take it another round.
- Once the plan has taken in everything you asked of it, **Accept the plan**
  puts it on a project as a task, with the plan written out beside it. A new
  project is one of the choices, and it is only ever made because you chose it.

A round with the agent takes a minute or two. The page doesn't wait for it: it
says a round is going and reads again every few seconds until it's done. The
rest of the time it reads every quarter of a minute or so, which catches
anything changed from a terminal. It redraws only when something has changed,
and never while you have something typed in a box, so an answer half-written
isn't thrown away by the page catching up.

Every button runs the command you'd otherwise type, `loadout idea answer` and
the rest, so what the page can do and what the command line can do are the
same thing. A round started from the page carries on if you close the tab,
because it's run by the dashboard, not the browser. If you stop the dashboard,
the round stops with it; the idea says where it got to either way.

### 10. Keep your tasks, and run a team on one

Open the **Tasks** tab. It's every project's task list and the workspace-wide
one, the same lists `loadout task list` reads, with what's being done first,
then what's blocked, then what's open. Done and dropped tasks are folded away
under each list. Ideas aren't here: they have their own tab, and a task they
become turns up here once you accept it.

- **Add a task** puts one on a list as open. Its id is made from the title, so
  you're asked what it is rather than what to call it.
- Each task opens to show its note and its buttons: start it, mark it done,
  drop it, reopen it, or move it back to open. **Mark it blocked** asks what it's
  waiting on, because a blocked task that doesn't say why is one somebody has to
  go and ask about.
- **Edit the title and note** changes either. Emptying the note clears it.
- **Remove** deletes the row, after asking. If you want a record that it
  wasn't done, drop it instead.
- **Run a team** starts a team on the task with nothing to choose. The goal is
  the task's title, with its note beneath, and the team's own autonomy, budget
  and done-when criteria apply. The task moves to doing, and to done or blocked
  when the run ends; the run doesn't add a task of its own beside it.

The team is `iterating-project` unless you've named another:

```sh
loadout config set team-for-tasks bug-hunt
```

One team for every task is what makes it a single click. When a task wants a
different team, or a budget of its own, use **Run a team** at the top of the
runs pane instead. A task on the workspace-wide list has no repository to work
in, so it has no run button; move it to a project first.

Like the ideas page, it redraws only when something has changed, and never
while you have something typed in a box.

## Only watching

For a screen in a corner, start it so nothing on the page can change a run:

```sh
loadout dashboard --watch-only
```

The server refuses anything that would start or change a run, or change an
idea or a task, and the page puts its controls away rather than showing buttons
that do nothing. The ideas and tasks are still there to read.

## If it went wrong

- **The page says the token is wrong.** The dashboard was restarted; copy the
  new address from the terminal.
- **The buttons are missing.** It was started with `--watch-only`.
- **The page is plain when you expected rich.** Your profile chose it. Use
  `--view rich` or the **Plain view** button.

## What this doesn't do

- It fetches nothing from the internet. Its typeface, Atkinson Hyperlegible,
  and the Loadout icon are carried inside the page. The office's art ships with
  Loadout and is served from your own machine.
- Only the dashboard's own machine can reach it by default.
- No screen reader has been used with it, and no keyboard-only pass by a person
  has been recorded. [Setting up accessibility](accessibility.md) has what was
  checked.

## Next

[Running a team](teams.md)