app/docs/interface/index.md

# The dashboard app

The web interface is a single-page app served at `app.${DOMAIN}`, or, for an
instance reached through a portal, at `${DOMAIN}/i/{instance-id}`.
Either way it is the same application, and it is a client of the same REST API
you can script against.

Sign in with the account the instance was created with. On a fresh
instance that account was printed once, on the first start.

## The shell

A floating sidebar on the left, the selected screen filling the rest. On a
phone the sidebar collapses to a sheet.

| Entry | What lives there |
|---|---|
| **Home** | the brain graph, health, and everything that recently happened |
| **Flows** | the list of flows, and the canvas for each |
| **Dashboards** | the widget canvases, and the panels that display them |
| **Runs** | starting a run with values you choose, and the log of what ran |
| **Workers** | the machines that nodes can be placed on |
| **Secrets** | credentials your nodes reference without holding |
| **Modules** | the Python packages your node code may import |
| **Alerts** | where failures get sent |
| **Admin** | users (superusers only) |
| **Search** | anything in this instance, by name |
| **Settings** | your account, appearance, remote access, and the assistant |

### Search

**Search** at the foot of the sidebar, or ⌘K / Ctrl-K from anywhere, opens a
panel that finds things by name as you type: flows with the nodes inside them
and the inputs and outputs they declare, dashboards and the widgets on them,
panels, secrets, modules, workers and alert channels. Picking a node opens its
flow with that node in focus, an input or output opens its flow's settings,
where it is declared, and a widget opens its dashboard.

It searches this instance. Reached through a portal, other instances
are behind **All instances** at the top of the sidebar.

## Home

The one screen you leave open. Four things share it.

### The brain graph

Every flow drawn as a neuron, wired to the flows it exchanges messages with.
This is the brand mark made live, and it is also the fastest read on the
instance: a neuron pulses when its flow is running work, and its ring turns
terracotta when the flow cannot run as written. A neuron with a problem keeps
its label showing so you can see which one it is without hovering.

Each flow also has a switch beside it in the list, which starts and stops it.

A [`wren` node](../reference/node-types.md#wren) anywhere adds a chat button
at the graph's top right, in the header on a phone, which opens the chat on
its [Control tab](../code/agents.md#control).

### Flows and dashboards

Two columns under the graph, exactly as tall as each other, most recently
worked on first. The flows column is the list with the switches; the dashboards
column is a mosaic, each tile a schematic of that dashboard's layout: blocks
where its widgets sit, shaded by what kind of widget each one is. Neither
column grows past about six rows: past that it scrolls in place rather than
pushing the health block down the page.

The tiles are a footprint, not a live view. They show you which dashboard is
which at a glance; the readings are on the dashboard itself.

### Health

Always answers, degraded or not. The tiles cover:

- **Flows** — total, running, paused, quarantined, and how many cannot run
  because their graph does not validate
- **Nodes** — how many failed to load
- **Runs running** — batch runs in flight right now, and how many are
  waiting. Only on an instance that has run something
- **Queue** — depth, and how old the oldest pending item is
- **Loop lag** — whether the engine's event loop is keeping up

`status: degraded` comes with a list of named problems, in words. "3 flow(s)
cannot run: house, pv, hallway" is more useful than a red dot, so that is what
it says.

### Activity

Charts of executions and failures over the selected range (1h / 6h / 24h / 7d),
with the recent runs, recent failures, dead-lettered work and the audit trail
underneath.

The charts are scrubbable: hover a moment and the lists below filter to it,
click to hold it while you read. That turns "something went wrong around two
o'clock" into the actual rows.

## Flows

The list shows each flow's title, node count, whether it has unpublished
changes, and whether it is enabled, paused or quarantined. The toolbar searches,
creates, and offers **Publish all changes** when several flows have drafts.

Opening one takes you to [the flow editor](flow-editor.md).

### Deleting several at once

Press and hold a card, or ctrl-click it, to pick it, then tap the rest. While
anything is picked, **New flow** in the toolbar becomes a trash button, and it
asks once before deleting the lot. Unpicking the last one puts the list back;
so does Escape. The Dashboards screen works the same way.

## Everything else

- [The flow editor](flow-editor.md) — the canvas, the code editor, running and
  testing
- [Dashboards and panels](dashboards.md) — widgets, bindings, and hanging a
  screen on a wall
- [Secrets, modules and alerts](operations.md) — the three screens that keep an
  instance running
- [Accounts and the portal](portal.md) — reaching an instance from outside
  its network

## Appearance

Light and dark follow your system by default; **Settings → Appearance**
overrides it. Both themes are first-class, and the wall-panel view is designed
to be legible in dark from across a room.