Where a Setting Belongs

The gear in the top bar opened a panel that only read. On the machine that runs the vault, the interesting question is not what the file says but what the process is doing. Then it learned to write, and every question got harder.

The Gear That Only Read

The first version listed every knob in file order with its value, its origin (this file, the environment, the code’s default), and whether a change needed a new process. It re-read the file on every request, so an SSH edit showed up as drift—the file says one thing, the process another—instead of being hidden by the next save. A tool knob showed the absolute path the process uses; a bare pdftotext is an instruction to search PATH, not an answer. On a machine reached over SSH, where a restart to check a knob is not free, that was worth shipping alone.

The File Is the Record

Writing YAML is easy until it has to be respectful. The writer replaces only the scalars a patch names in the node tree: comments survive, a ${VAR} stays a reference, the old bytes are kept as <file>.bak before an atomic rename, and a broken file refuses the patch. The subtle part was the order. applyDefaults turns a zero worker count into four; a writer that validated afterwards would store parallel_runs: 0 while the app ran four workers—the exact lie the read-only panel existed to expose. The check runs before the defaults, answers 400 for a key outside the allowlist or an environment-owned value, 422 for a value the app cannot use, and leaves the file untouched.

Nothing Changes Under a Run

This is a desktop app with a pipeline, and a document step and the cluster pass exclude each other through one gate. A config change must not become a third writer. The apply rebuilds the wiring as a unit—a new Deps, Config and HTTP handler—and swaps all three behind the exclusive gate. A running step finishes first; an in-flight call keeps the wiring it started with. Distill and query workers are a generation: the old ones finish the job they hold, the new ones start with the new counts. The cadences are read every tick; the heap ceiling goes to the runtime. The answer says queued, and the overlay follows until file and process agree—milliseconds, usually one request, no restart.

The Pencil, Not the Form

The first editing UI kept a form on screen. That promises every field is about to change; the values here are mostly read. A value stays text until its pencil is pressed, and only that row opens. The input is laid over the value instead of beside it, so the row keeps its width, height and baseline—measured pixel-identical—and the line cannot twitch. Enter saves, Escape closes, Save or Revert commits. Secrets, environment-owned values and the vault/index paths never get a pencil: the API key is set or not set, a header map reveals only names.

The Expert Surface

Sixty-five knobs turned out to be writable, too many to show unasked. The curated set—language, models, the inbox automation, parallelism, capture cadences—stays visible; the rest sits behind an Advanced switch: timeouts, retries, the run and cluster ceilings, the reconcile cadence, capture thresholds, the cluster arithmetic, the assistant limits, the browser and OCR tools. Opening it warns what an apply means; a search still finds an expert row. The surface also forced two latent bugs into the open: pdf.max_pages was never read, and ocr.max_pages cut the whole PDF walk. A knob you can edit is a knob that has to work.

Two Owners

The last question was ownership. The claim language, the capture cadences and thresholds, the OCR languages, the assistant’s history window and the cluster arithmetic are properties of the corpus, not of the machine. They lived in the machine’s config, so a vault moved to another machine took its claims but not the settings that produced them. They now live in an optional vault.yaml next to index.db: a key the vault declares wins, so it travels; a key it leaves out falls back, so an installation without the file behaves as before. The first save creates the file with a header and only the keys that save touched; a machine key in it—the listener, a path, the interface language—is refused with its name. The overlay shows the file, its path and the chip VAULT.

The Numbers

90 knobs: 65 writable (21 curated, 44 behind the reveal), 25 read-only on purpose, 19 of them owned by the vault. The apply finishes in milliseconds, in the running process. The write path is two files, a backup for each that existed, and one gate.

What Is Still Open

The apply is not in the Status job queue yet, so a long step can outlast the overlay’s poll. capture.dedupe_by_url is inert—URL identity is the hash. Restart automation waits for a knob that needs it. The open design question is scale: a flat list with a reveal, or config files per concern.

A settings screen is not a form; it is a map of ownership and trust: what the machine owns, what the vault owns, what may change while a run is in flight, and what the app must refuse to edit. The honesty—the origin of every value, the gate, the refusal to write a number the app would silently replace—is the feature. The split will outlive the screen: a setting is a claim about where knowledge lives.