The operator's companion

Status: Accepted · Audience: Operator · Area: N — Companion

---

Purpose

What the operator opens the app to find out, and what they can do about it without going to the machine.

The ordering is deliberate and is the whole design: is anything wrong, then what, then may I fix it from here. A dashboard that leads with statistics answers a question nobody opened the app to ask.

This is the surface where lemonfiber’s own difference shows most: the product already knows what is wrong in plain language, already knows what would put it right, already asks before changing anything, and already records what it did so it can be undone (C1, C3). None of that is invented here. This feature renders it on a phone.

Behaviour

It opens on the answer, not on the data

The first screen is the overall verdict (G7) — healthy, degraded, broken, or unknown — and unknown is a first-class answer rather than a blank. Beneath it is what is wrong, worst first.

A finding carries its remedy, and the remedy is offered

Every problem lemonfiber raises carries a code, what it means in plain language, and what to do (G4). The meaning and what to do are on the finding; the code is one step away, available and not leading (G4-R4). A finding about a service carries its code to the log view its card opens, where it is said above the lines, and a finding about the machine, which has no log to open, carries it in the detail at the foot of its card.

Where the product can put it right itself, the repair is offered here on the same terms it is offered anywhere: what it would do, what else changes, whether it can be undone, and a confirmation before it happens.

A repair is never carried out because the operator tapped the finding.

The stack’s life is controllable

Starting, stopping and restarting, by form or by service (B2). A destructive or disruptive action asks first, and says what it disturbs and how long for — as the stack reported it. The stack answers that with a bound where it has one and with open-ended where it does not (B2-R16), and the app states whichever it was given. It does not estimate: a duration worked out in the app would be a guess at something the stack knows and the app does not, wrong in exactly the cases an operator most needs it, and wrong silently, because nothing on either side would ever compare it to what happened.

A start says what it is waiting for, in the stack’s words

A start is not waited for by the request that asked for it: the stack answers with a name for the work, and what the start is doing arrives afterwards on the event stream, as lines of the start kind: how long it will take services away for, and then which services it is still waiting on and how far into its time it is (B2 B2-R2). Each line replaces the one before, because only the newest says what the wait is waiting for now.

While a start the operator asked for runs, those lines are what the app shows. A bar or a spinner of the app’s own in their place would say that something is happening, which the operator knew, and hide what, which is the only thing they opened the screen to learn.

Images can be fetched ahead of a start

A start fetches whatever images it is missing before it can start anything, and on a slow line that is the longest part of it. Fetching them ahead of the start lets the operator choose when that happens, so the app offers it on its own (B2-R12). What it came to is the stack’s answer to a lifecycle command.

Before it runs, the app says that it may take long and may use a lot of the line. It gives no figure for either: nothing the stack says bounds a fetch, and B2-R16’s answer for a pull over an unknown connection is that it is open-ended.

An update is a decision, not a number

Whether the stack is current is an answer, and the app opens on it the way it opens on everything else here (E1). An operator holding a phone is not comparing version strings; they are deciding whether tonight is the night.

So what is offered is what the decision needs. That a release is user-facing is the distinction that matters on this surface — a change somebody in the house will notice is a different decision from a patch nobody will — and a release that has been withdrawn is not an update at all. Applying one asks first, and says which services it would change, because an update of eight services and an update of one are different evenings.

Undoing is part of the offer, and the two ways of undoing are not interchangeable. A rollback puts the previous version back; a restore puts back what was there (E4). Which one is available is the stack’s answer per service, and an app that flattened them into undo would be promising a thing it cannot tell it has. Where the stack named neither, nothing is offered — an undo that is not there is worse than none, because it is what somebody agreed to the update on the strength of.

What was read is what is agreed to. Applying an update, and restarting what the operator asked about, carry back the offer the stack answered with when the operator read what each would do (web API). Between reading and agreeing a release can arrive or a service can change, and an agreement that named nothing would be spent on whatever stands by then. The stack refuses an offer that has moved, and the app reads it again and offers what it says now, as it does for a repair.

Afterwards, each service says how it ended, and not fetched, not started and not reached are three different evenings too: one is a network, one is the service, one is the machine. A single failed would send an operator looking in the wrong place.

A part that moves in place is its own change

A release can run a part of the stack as a plugin where this machine still runs it as the stack’s own service. Moving it in place keeps its container, its configuration, its data and its credentials, and a confirmed update is what takes it (F14 F14-R29, ARCH-R299). That changes what answers for the part, not only its version, so the confirmation names each move on its own: the stack’s own service, and the plugin that would take its place.

Afterwards each move says how it ended: taken, or not taken and why, in the stack’s words. A move not taken leaves the service running as it was, which is not the same as a service the update failed.

A start takes no move. Where moves are on offer, what a start came to names each the same way and says that an update takes it, so an operator who only started the stack does not read the part as already moved.

The things that go wrong while nobody is watching

Downloads that are stuck (C7), a provider out of allowance or refusing a login (C8), a disk filling (D5), a tunnel that is up with no forwarded port (C2). These are the ones worth carrying in a pocket, because each is invisible until something the household wanted does not arrive.

Logs are readable, not tailed

A phone is a bad terminal. Logs are offered as a bounded, searchable read for a named service (B4) rather than as an endless stream, and the app says it is showing a window rather than everything.

Requests waiting on the operator

A household member’s request that needs a decision is surfaced here, with enough to decide on (D7). Approving from a phone is the case this whole surface justifies itself with.

What the household is playing now

The operator can see every session the media server is playing: who is watching, the title or the series, season and episode, on which device, and whether it is paused. The list follows the stack’s playing event, so it stays current without the operator asking, says so plainly when nothing is playing, and says when it last heard where the stream has stopped. It is the operator’s: a member is never shown it, nor anybody else’s session.

What it does not do

Nothing here edits a credential’s value. The app can report that a credential is refused and offer the reconciliation lemonfiber already has; it is not a place to type a provider password into over a LAN.

Seeing what the household sees

The operator runs everything a member uses, so the operator can open the member’s application as a member would meet it: the household’s default access and allowance, in the member theme, marked as a preview. It is nobody in particular. A named member’s requests and what they watched stay theirs. It opens from View as member in the operator’s menu (N28).

The preview is read only. Asking for something from it would be a real request made under the operator, so the control that asks is drawn and cannot be used, and a note beside it says a preview cannot ask.

States

Edge cases

Acceptance criteria

Notes

What the contract carries for N2-R23 and N2-R24. Checked against the core’s contract/web-api/, its event stream and the actions its HTTP route accepts.

The gaps in bold are the contract’s to close, and until they are N2-R14 applies: the app says what its rows require and substitutes no figure of its own.

Related

• N1 — connecting, and what the app may claim
• C1, C3 — the findings and repairs rendered here
• G7 — the verdict this opens on
• G4 — the words a problem is given
• D7 — the requests waiting