Lemonfiber
← The specification

Reconfiguration

Rendered from spec at76d46f3 (2026-10-25) · its source · Edit this page

Status: Accepted · Audience: Operator · Area: A — Getting started

Purpose

Every decision made during setup must be changeable afterwards, without starting over and without hand-editing configuration files.

Setup asks fifteen questions when the operator knows least about the system. Some answers will be wrong. Without a first-class way to revise them, the operator’s only options are to edit files they were never meant to see, or to tear everything down and re-run setup — which risks their library.

An unchangeable decision is a trap, and a product full of traps teaches people not to touch it.

Behaviour

Any setup answer can be revisited individually

The operator changes one thing without being walked through the other fourteen. Reconfiguration presents the current configuration as a set of editable decisions, each showing its present value and what changing it will affect.

Consequences are stated before the change is applied

Reconfiguration divides sharply into two kinds, and the distinction must be visible:

Kind Examples Behaviour
Cheap Timezone, quality preset, notification targets, bandwidth schedule Applied with a restart of the affected services
Consequential Data location, storage mode, Jellyfin mode, protocols Requires confirmation, may require moving data, may invalidate library paths

Changing the data location is the sharpest example: every *arr holds absolute paths to its root folders. Moving DATA_ROOT without updating them leaves a library that points at nothing. lemonfiber MUST detect this and either update the paths or refuse and explain — never apply the change and leave the operator to discover the breakage.

Adding a capability later is a supported path, not a repair

The most common reconfiguration is additive: someone starts library-only, then wants Usenet; or starts Usenet-only, then wants torrents. Each of these opens exactly the prerequisites and credentials that the new capability needs, and nothing else.

Someone who began with zero paid services should be able to grow into a full stack incrementally, one decision at a time.

Removing a capability is equally supported

Dropping torrents stops and removes the download client and VPN, and disables the forms that required them — while explicitly not touching downloaded content. The operator is told what will stop, what will be removed, and what will be kept.

Nothing is applied until confirmed

The same rule as A2: a review step showing the diff between current and proposed configuration, and no writes before confirmation.

On the companion

Revisiting a setup answer is not first-run setup, and N15-R1 is what stops that distinction collapsing on a surface that declines the latter (N15): what setup settled is shown as facts about the stack, and showing them is not treated as offering setup.

Consequences are stated before the change is applied takes a particular form when the change is a reset. N6-R8 requires resetting configuration described by what changed and which connections went with it, rather than by a reassurance (N6). Reset means very different amounts depending on what had been set, and an operator agreeing to one from a phone has no other way to find out which amount they agreed to.

States

State Meaning
clean Configuration matches what lemonfiber last wrote
pending Changes staged, not applied
applying Writing and restarting affected services
drifted Configuration was changed outside lemonfiber — see C9
blocked A staged change cannot be applied safely; reason stated

Edge cases

Situation Behaviour
Data location changed with an existing library Detect it. Offer to move the data, or to re-point the configuration at the existing location. Never silently leave the *arrs pointing at absent paths.
New data location can’t hardlink but the old one could Warn that imports will degrade to copies, and require confirmation.
Protocols reduced while downloads are active Report what’s in flight and offer to wait, or to stop and lose progress. Don’t silently discard active work.
Jellyfin switched docker→native Config and library paths must be migrated; state exactly what the operator must install and do by hand, since a package manager action can’t be taken on their behalf.
VPN credentials replaced Validate the new ones before discarding the old, so a bad paste doesn’t leave the operator with no working tunnel.
Configuration was edited by hand outside lemonfiber Detected as drifted. Show the difference and let the operator choose which side wins. Never silently overwrite their edit.
Change requires a service that isn’t running State it and offer to start it, rather than failing obscurely.
Operator reduces quality preset with existing library Clarify that it affects future grabs only; existing files are untouched unless an upgrade is separately requested.
Timezone change Applied cheaply, but note that *arr schedules shift accordingly.
Household disabled after invitations were sent Existing accounts are retained by default; deleting them is a separate, explicit action.

Acceptance criteria

ID Requirement
A4-R1 Every decision made during A2 MUST be individually revisable without re-running the full wizard.
A4-R2 Each change MUST state its consequences before being applied.
A4-R3 Changes MUST be classified as cheap or consequential, and consequential changes MUST require explicit confirmation.
A4-R4 A review step MUST show the diff between current and proposed configuration; nothing MAY be written before confirmation.
A4-R5 Changing the data location MUST detect existing library paths and MUST either update them or refuse with an explanation.
A4-R6 Adding a protocol MUST open only the prerequisites and credentials that protocol requires.
A4-R7 Removing a protocol MUST NOT delete downloaded or imported content, and MUST state what is kept.
A4-R8 Replacement credentials MUST be validated before the previous ones are discarded.
A4-R9 Reconfiguration MUST detect out-of-band configuration edits and MUST NOT silently overwrite them.
A4-R10 Reducing capability while work is in flight MUST report what is active and offer to wait.
A4-R11 A change that cannot be applied safely MUST leave configuration unmodified and MUST state why.
A4-R12 Quality preset changes MUST state that they affect future acquisitions only.
A4-R13 LEMONFIBER_IDEMPOTENCY_MINUTES and LEMONFIBER_IDEMPOTENCY_KEYS MUST be changeable and shown, with where each came from, by lemonfiber config, as every LEMONFIBER_* key outside the core settings is (ARCH-R278); a value for the first that is not a whole number from 1 to 1440, or for the second one from 1 to 4096, MUST be refused naming the setting and its range and MUST leave configuration unmodified, and a value outside its range that reached the file another way MUST be read as the setting’s default (web API).