How it works
Modules and first run
A home install shows what a home roaster uses; Enthusiast and Roastery presets switch on the rest. Weight units, traceability.
Roastwarden does more than a home roaster needs: PDF reports, cupping, autotune, bag labels, costs, tokens for agents. Modules switch the optional parts off. A home install shows the roast, its history, profiles, beans and roasters, and nothing else in the way. Turn a module back on and everything it held is still there.
The first run
A new install (nothing set up yet, no roast and no bean) opens a Welcome page once, in place of the Roast page. It asks four things:
- What kind of roasting? Home, Enthusiast or Roastery: a preset of modules (below).
- Temperatures in °C or °F.
- Weights in g, kg or oz, lb.
- Time zone: this browser's zone is filled in. It sets the day a roast falls on, for labels and reports.
Save and add a roaster saves them and opens Roasters → Add (or the simulator's page when the simulated roaster is the only one). Not now saves Home and opens the Roast page. All of it can be changed later in Settings.
Presets and modules
Settings → Modules: pick a preset, or switch modules one by one ("Your own mix").
| Preset | What it shows |
|---|---|
| Home | no modules: Roast, History, Profiles, Beans (green stock, roasted coffee and planned roasts, no prices), Roasters, Settings |
| Enthusiast | Home, plus Reports, Cupping, Tuning, and Agents & access |
| Roastery | everything: adds Costs and Labels, for selling coffee |
| Module | What it adds |
|---|---|
| Reports | PDF reports: the Reports section and a roast's Report button |
| Cupping | the cupping form and its scores on a roast |
| Tuning | autotune, the gain schedule and fan assist on a roaster's pages. The PID and Profile drive stay: they follow the roaster's control level |
| Agents & access | Settings → Tokens, Approvals and Audit, for scripts and agents |
| Costs | prices on purchases, cost per kg and per roast, spending and the shopping list |
| Labels | the Labels section (Label Studio), a roast's labels and the share pages their QR codes open |
Some parts are never modules: the Roast page, alarms, guidance, notifications, history, profiles, green stock and roasted coffee, and the roasters with their check.
What switching a module off does:
- It leaves the menu bar, Settings' menu and the buttons that lead to it. A link to one of its pages shows one line instead, such as "Labels are off: Settings → Modules".
- Nothing is deleted. Turn it back on and its data is there.
- It is not a lock. The API stays open to scripts and the
roastcommand line, and tokens still decide what they may do. An agent with the Roastwarden skill reads the modules and does not offer what is off; ask it again and it goes ahead.
An install that has never saved the setting has every module on.
From the command line: roast modules shows what is on and the preset it matches;
roast modules --preset home, --on labels or --off cupping change it (an admin token).
Weight units
Settings → This browser → Weight unit, per browser like °C and °F:
- Metric: grams, then kilograms from 1 kg.
- US: ounces, then pounds from 1 lb. Prices per kg show per lb.
A weight field takes a number with a unit ("250 g", "8 oz", "2 lb", "1.5kg"); a bare number is grams or ounces, and the field says which. The server stores grams whatever you pick. Labels print both ("250 g · 8.8 oz"), and reports have their own unit setting under Settings → Roasting.
Packed bags and ground coffee
On a roasted lot, Beans → Roasted coffee → Packed… records bags packed from it: how many and their size ("3x250g"), whole bean or ground with a grind (espresso, filter, moka, French press, or your own word), and the date. The grams come off the lot, but are not counted as used. A label print for the roast can do the same: its dialog has "Take 3 × 250 g off this roast", on when that much is left.
A ground bag's label reads "Ground · espresso" where a whole-bean one reads "Whole bean". Ground coffee goes stale sooner: its "best until" is the earlier of the lot's and the pack date plus Ground, at its best for (Settings → Roasting, 14 days unless you change it). More on lots and their moves in roasted coffee.
From the command line: roast roasted pack <roast> 3x250g --ground espresso.
Traceability
A bag's batch number leads back to its green coffee. Reports → Traceability (or
roast trace <roast|coffee>) shows the green coffee (supplier, lot, origin, process,
purchases), each roast of it (batch number, date, roaster, profile, green and roasted weight,
loss) and where the coffee went: packed bags with form and grind, label runs, gifts with the
recipient, used, discarded, and what is left. It holds no prices.
Profiles for your kind of roaster
A profile may say which kind of roaster it was written for. The seed profiles include the fluid-bed ones and two for a gas drum (a light filter and a medium omni roast). The profile library lists those for the selected roaster's kind first and marks the others ("for a drum", "for a fluid bed"); nothing is hidden. A profile saved from a roast takes its roaster's kind; one with no kind fits any roaster. See profiles.