john-slop/docs/configuration.md

2.1 KiB

Configuration

John Slop embeds schema-versioned replacement and heuristic catalogs in every binary. Installed binaries therefore work without a source checkout or external default files.

Precedence

Configuration layers are applied from lowest to highest priority:

  1. embedded assets/config.toml and assets/heuristics.toml;
  2. the platform user file config.toml;
  3. a selected user <config_name>.toml;
  4. an explicit --config <FILE>;
  5. configuration flags for the current invocation.

On Linux, the user directory conventionally resolves to ~/.config/john_slop. John Slop uses operating-system APIs rather than reading HOME directly, so Windows and macOS receive their native application config directories. Run this to inspect the exact paths on the current machine:

john-slop config paths

Named configurations accept only ASCII letters, digits, _, and -. Do not include a directory, dot component, or .toml extension. Missing user and named files are optional; a selected explicit file must exist.

Schema

The current schema_version is 1. The complete defaults and documented record examples live in assets/config.toml and assets/heuristics.toml.

Replacement and heuristic arrays merge by stable id. A partial record changes only the supplied fields:

[[replacements]]
id = "em-dash"
enabled = false

[[rules]]
id = "templated-conclusion"
weight = 2.5

A new ID must provide every field. Scope extension arrays replace the prior array as a whole. Unknown keys, malformed TOML, duplicate IDs within one layer, invalid regular expressions, unsafe matchers, non-ASCII replacement targets, and invalid thresholds are fatal configuration diagnostics.

Inspection

Print the fully layered and validated model as deterministic TOML:

john-slop config show
john-slop config show --config project.toml
john-slop config show --config-name strict

The output contains no secrets in schema version 1. If secret-bearing fields are introduced later, inspection output must redact them by default.