← Roteiro home · All ADRs

ADR-0007: Configuration file — a single project-level TOML with layered precedence

Reference

Introduces a persistent configuration file so per-project preferences (which models to use, what to ingest, inference thresholds, ignore paths, serving) are set once and shared, rather than re-passed as CLI flags every run. It gives a home to settings spread across ADR-0003 (model picks), ADR-0005 (image ingestion toggles), and ADR-0006 (the [serve] table). Governed by the offline/deterministic principles of ADR-0001.

Summary

Add an optional roteiro.toml at the repository root (committed — so a team shares the same, reproducible settings), plus an optional user-level ~/.roteiro/config.toml, with a clear precedence:

CLI flag > project roteiro.toml > user ~/.roteiro/config.toml > built-in default.

One rule inverts this order (v1.4). For a capability key — one whose effect is to turn something on whose cost or risk falls on whoever runs the command — the project file may deny but never grant.

This began as a single documented exception for the remote tier in v1.2. It is now the standard, because an exception list grows one entry at a time until it is the rule and nobody has noticed. A rule with a stated scope can be applied to a new key by whoever adds it; an exception list can only be extended by whoever remembers it exists.

The reason is in this ADR's own words: roteiro.toml is "committed — so a team shares the same, reproducible settings". That is exactly right for a setting and exactly wrong for a permission. A merged line that starts sending source elsewhere, or running builds, on every teammate's machine is consent by pull request — granted by someone else, noticed by nobody. The project layer may switch such a capability off for everyone, and may never switch it on for anyone.

Which keys this covers

A key is a capability key if setting it causes something to happen that otherwise would not, and that thing does at least one of:

1. sends repository content off the machine;
2. executes code the repository supplies, rather than code Roteiro ships;
3. writes outside the repository and Roteiro's own caches, that would not otherwise occur — Roteiro already writes to ~/.roteiro by default, so a key that changes where rather than whether does not qualify;
4. spends materially more of the machine than an ordinary command — loading a multi-gigabyte model, or running a build;
5. removes a guard against any of the above. A guard is disabled by setting something to false, so this clause exists because such a key is a grant wearing a denial's grammar and would otherwise have to be caught by noticing that one of 1–4 applies transitively.

A capability key's built-in default is denied. If a key defaults to granted, then setting it in a project file causes nothing that would not otherwise happen — it fails clause 1 of the test before any of 1–5 is reached — and it is a value. Whatever does gate the behaviour is the real capability, and it is that which the rule governs. This is not a caveat; it is how three of the keys below are classified.

Everything else is a value, and values follow the ordinary order above. Most keys are values, and for them the inversion is not merely unnecessary but inexpressible: there is no "deny" for [models] generative = "qwen3-8b", only a different value.

Two of those rows are worth reading as method rather than as answers. [ingest] was expected to be a capability and is not, because its default already grants — which is what produced the default rule above, and is a reminder that a key's class cannot be read off its subject matter. [media] gate is the reverse: an unremarkable-looking boolean that turns out to be the only key here whose false is the dangerous value.

A third case the classification did not have a name for (v1.5)

[mcp] tools restricts what an MCP server advertises. It is a value by this ADR's own default rule — the built-in surface is every tool, so naming a subset in a committed roteiro.toml grants nothing that was not already granted, and the capability test fails at its first clause. But applying the ordinary precedence to it would have been wrong, and the reason is worth recording because the abstract rule did not reach it.

Every setting of the key is a denial. Naming a tool does not ask for that tool; it declines every tool not named. So "the nearer layer wins" lets a nearer layer un-deny: a committed project file could restore sandbox_clear after the machine's owner removed it in ~/.roteiro/config.toml. That is exactly the outcome v1.2's inversion exists to prevent, reached from the other direction — not by a project file granting a capability, but by a project file cancelling a denial.

The rule is therefore: a key whose every setting is a denial layers by intersection. Every layer may narrow, none may widen, the invocation included. The flag narrows rather than winning because a flag has nothing else to express here — there is no grant available to it, exactly as this ADR says of a value key that "there is no deny for [models] generative, only a different value" — and because an MCP invocation is argv in a client's configuration file — written once by whoever wired that client up, then committed and shared — so the invocation is not reliably a person at a prompt, while the user layer is unambiguously that person's standing intent.

Intersection is a lattice meet: order-independent, idempotent and monotone downwards, so "may deny, may not grant" holds by construction rather than by a rule each call site remembers — which is what the section below requires. An empty intersection is a startup error, never an unrestricted server: a restriction that quietly restricts nothing is the defect the key was added for (issue #584, and omnigent#5178 on the client side of the same wire).

The key sits in its own [mcp] table rather than in [serve] because [serve] tools is taken and means something else — a boolean deciding whether the served-chat model is offered the graph tools at all. Two keys called tools in one table, over two different surfaces, would be worse than a second table.

The mechanism is structural, not remembered

RemoteConfig implements the inversion with a bespoke overlaid_with. A second bespoke implementation is how a rule decays into a convention, and a third is how a convention decays into folklore. A capability key's layering must therefore be carried by its type, so that declaring a key a capability and getting its precedence right are the same act rather than two things a future author has to remember to do together — the same reasoning that put debt exclusions behind one function and truncation behind one window.

roteiro config reports a key's class beside its layer, because a reader who sees one key inherit and its neighbour refuse to cannot otherwise tell whether that is the rule or a bug.

Three states, because two of the requests are not the same one (v1.9)

[paths] exclude and [paths] opaque are the only keys here that decide what is in the graph rather than how it is reported, and that is the whole reason they exist. Before them there was no mechanism to exclude a path from extraction at all (issue #840): the one exclusion list in this file is [debt] ignore, which is scoped to markers and filters the report. The node stays in the store, and search, explain, list_kind, path and export all still see it — so a repository could suppress a false finding from the report it reads and still publish it to a consumer.

The two keys are two of three states, and the third is the default:

"Do not mine this as configuration" and "do not put this in the graph" are different requests and two live decisions need one each, which is why two states would not do. A fourth — in the graph, mined, but muted from the reports — already exists and is [debt] ignore; it is deliberately not reproduced here.

The rule is consulted by every reader, and this is the part that is easy to under-build. There are two independent readers of committed blobs: derived extraction, and the authored layer, which walks every path on its own and classifies by content, not by location. A document that declares type: adr is parsed as one of this project's decisions wherever it sits — the rule that lets a repository keep its decisions outside docs/adr/, and exactly what makes an ingested third-party document dangerous. An exclusion applied at extraction alone would therefore remove a manifest's config_key nodes while still parsing a stranger's paper as one of ours. The policy is carried in the resolved ingestion configuration, which already reaches every entry point that reads repository bytes, so a reader that has one has the other.

Nothing is excluded by a built-in default — not raw/, not vendor/. A built-in would silently drop a directory out of the graph of every repository that happens to have one, on upgrade, with nothing said, and the only way to notice would be to know the default existed. Declaring is visible in review; un-declaring a default is not.

Both lists merge across layers, and neither has a reset. They merge for the reason [debt] ignore does (v1.1). They have no reset because a reset on an exclusion would let a committed project file widen what is read over a user's own declaration — re-admitting, on their machine, a corpus they excluded machine-wide, by a line somebody else merged. Narrowing is the safe direction for an exclusion, so only narrowing is expressible. That is the same asymmetry v1.4's capability rule draws, reached from the other side: there the project layer may deny and not grant; here it may only subtract, so there is nothing to invert.

A path matching both lists is excluded: between two declarations about the same bytes, the narrower one wins.

Format: TOML, and only TOML. Not YAML.

• TOML is the idiomatic Rust/Cargo choice and the toml crate is well-maintained.
• serde_yaml is archived/unmaintained (deprecated by its author in 2024) — adopting YAML would add a cargo deny/maintenance liability, and supporting two formats is redundant surface for no gain.

The file is entirely optional — every key has a working default, so Roteiro runs with no config at all; the file only overrides defaults. Unknown keys are ignored (forward-compatible), and a malformed file is a hard error (never a silent partial parse).

Context

As Roteiro's surface has grown — a curated low/mid/high model matrix (ADR-0003), ingestion toggles (prose/PDF/OCR/vision, ADR-0005), inference/dedup thresholds, intent-debt ignore directives, and now serving (ADR-0006) — more behaviour is worth pinning per project rather than retyping as flags. A committed config also makes runs reproducible and shareable, which fits the dogfooded/deterministic ethos.

Forces to reconcile:

1. Optional & defaulted (ADR-0001). Roteiro must work with zero configuration; the file only ever overrides defaults. No config must never mean "broken."
2. Reproducible & shareable. A committed project file means a team gets identical behaviour; the user-level file is for personal, cross-project preferences (e.g. a default model tier for a beefy machine).
3. One well-maintained format. Rust's ecosystem standard is TOML; serde_yaml is unmaintained. One format, cleanly parsed, beats two.
4. Flags still win. A one-off --min-confidence 0.6 must override the file, so precedence is CLI > project > user > default.

Decision makers

• The Roteiro Project Team

Recommended option

Option 2 — a single optional roteiro.toml (+ user override), TOML-only, layered precedence (recommended).

Initial schema (all keys optional; every section defaulted). Start with the high-value "sticky" ones ([models], [ingest], [infer]) and grow:

[models]                       # per-project overrides of the tier defaults (ADR-0003)
embedding  = "bge-base-en-v1.5"     # `infer`
generative = "qwen3-8b"             # `spec draft` and the Ask panel
vision     = "smolvlm-500m-gguf"    # `media build`, image description   (v1.3)
audio      = "voxtral-mini-3b"      # `media build`, speech transcription (v1.3)
ocr        = "ocrs-text"            # `sync`, literal text in images      (v1.3)

[ingest]                       # which content types feed meta.content, + caps (ADR-0005)
pdf = true
image_ocr = false
image_vision = false
max_content_chars = 1500

[infer]
min_confidence = 0.4
top_k = 5

[duplicates]
min_similarity = 0.9

[debt]
ignore = ["vendor/**", "**/generated/*"]   # paths excluded from intent-debt

[serve]                        # ADR-0006
models = false
addr = "127.0.0.1:8080"

[paths]
model_store = "~/.roteiro/models"   # today only the ROTEIRO_HOME env var
exclude = ["raw/**"]                # not in the graph at all          (v1.9)
opaque  = ["manifest/**"]           # a file node, nothing mined       (v1.9)

• Loading: parse user file, then project file, then apply CLI flags — each layer overriding the previous; a missing file is simply skipped; a present-but-malformed file is a hard error naming the offending key/line.
• Scalars replace; the [debt] ignore exclusion list merges (v1.1). Replace is right for a scalar — there is one model, one addr, and the nearer layer names it. It is wrong for an exclusion list, where the intent is nearly always additive: a user who globally ignores vendor/** and then adds one project-specific thirdparty/** wants both, and silently narrowing the union to the project's single pattern makes the tool report debt the user believed excluded, with nothing to indicate why. To inherit nothing instead, set [debt] ignore_reset = true — an explicit, all-or-nothing reset rather than a !pattern negation, because a mistyped negation removes nothing and says nothing, which is the same silent-wrong-answer failure the merge exists to fix. Every exclusion list merges — three of them since v1.9, this one plus [paths] exclude and [paths] opaque, through the same matcher and for the same reason. They differ only in the reset: [debt] ignore has one, and the [paths] lists deliberately do not, because a reset on a key that decides what is in the graph would let a committed project file widen what is read over a user's own declaration. What stays replace-wins is unchanged: [workspace]/[standalone] roots/repos are discovery lists (a merge would silently serve repos the project never named) and [serve] models is a selection.
• A repository's own config governs how it is scanned, whoever is asking (v1.1). When one process serves several repos (ADR-0008), each repo's settings are read from that repo's root — the same per-repo resolution ADR-0009 already uses for [[links]]. Otherwise repo B, scanned from repo A, is measured under A's exclusions and B's operators cannot explain the number they are shown.
• Discovery: project file is roteiro.toml at the repo root (found alongside the git dir); user file is ~/.roteiro/config.toml (honouring ROTEIRO_HOME, consistent with the model store).
• Feature-availability honesty: a config key for an opt-in feature (e.g. ingest.image_vision) that the running binary was not built with produces a warning, not a silent no-op or a hard error — the setting is valid, the binary just can't honour it.
• A key whose value is wrong is a different thing, and it fails loudly (v1.3). The warn rule above is about a build that lacks a feature: the setting is correct and this binary cannot act on it. A [models] key naming a model that does not exist, or one of the wrong modality, is not that — it is wrong everywhere, and no rebuild fixes it. Those are named errors quoting the key, and never a fall-back to the default: a fall-back would leave the file appearing honoured while a different model ran, and on the llama.cpp path a model of the wrong architecture does not mis-answer, it aborts the process (GGML_ASSERT). The single exception is roteiro config itself, which reports the bad key rather than refusing — it is the command an operator runs precisely because a pin is not doing what they expected, so it must not be the one command the pin stops.

Options considered + consequences

Option 1: No config file — CLI flags + env only (status quo)

• Pros: nothing to build; fully explicit.
• Cons: sticky per-project preferences must be retyped every run; no shareable, reproducible project settings; env vars are a poor home for structured config. Rejected as the surface grows.

Option 2: A single optional TOML file with layered precedence (recommended)

• Pros: reproducible/shareable (committed project file); idiomatic, well-maintained format; optional and fully defaulted; flags still win; a natural home for model picks, ingestion, serving.
• Cons: a new parse path + precedence logic to get right (mitigated: small, well-tested, toml + serde); another place settings can live (mitigated: strict precedence + a roteiro config command can print the effective, merged config).

Option 3: Support both TOML and YAML

• Pros: familiarity for YAML users.
• Cons: serde_yaml is archived/unmaintained (deny/maintenance risk); two formats double the surface and invite drift for no real benefit. Rejected — TOML only.

Consequences

• A new optional roteiro.toml (project, committed) and ~/.roteiro/config.toml (user); zero-config still works — the file only overrides defaults. Adds the toml crate (permissive licence, cargo deny-clean) to the binary.
• Precedence is fixed and documented: CLI > project > user > default. A roteiro config command prints the effective merged configuration and its provenance (which layer set each value), so "why did it use that model?" is answerable. Per surface, since v1.3: the [models] keys alone stopped being an answer once six surfaces consumed five keys, two of them sharing one — so roteiro config also prints the resolved model for embed, draft, chat, transcribe, describe and ocr, each with the rule that chose it and, for a pin, the layer it came from. The same reasoning as the per-pattern [debt] ignore provenance below: report what the operator observes, not only the input it was derived from. For a merging exclusion list — [debt] ignore, and since v1.9 [paths] exclude and [paths] opaque — provenance is reported per pattern rather than per key, because a single label would misreport a list holding patterns from both layers; and an ignore_reset prints the inherited patterns it discarded, so the reset cannot hide what the merge was added to reveal. It matters more for [paths] than for [debt]: a reader asking "is my exclusion in force?" is asking about nodes that exist or do not, rather than about rows in a report.
• Settings currently only reachable by flag/env gain a persistent home: model picks (ADR-0003), ingestion toggles + caps (ADR-0005), inference/dedup thresholds, intent-debt ignore paths, the [serve] table (ADR-0006), and the model-store path (today only ROTEIRO_HOME).
• Forward-compatible: unknown keys are ignored; a malformed file fails loudly (never a silent partial parse). A key for a feature the binary lacks warns rather than errors.

Advice Received

Project direction incorporated: add a config file, but keep it optional and fully defaulted (no config must never break Roteiro), make it committed and reproducible at the project level with a personal user-level override, and use one well-maintained format — TOML, not YAML (since serde_yaml is unmaintained) — with CLI flags always winning.

Document version history

← Back to roteiro.dev