diff --git a/.run_status.toml b/.run_status.toml
index b64add1..f533395 100644
--- a/.run_status.toml
+++ b/.run_status.toml
@@ -1,8 +1,8 @@
[last_run_clean]
run_status = "Success"
-lines_parsed = 114
-coverage = 72.32
+lines_parsed = 130
+coverage = 73.13
[last_run_clean.run_duration]
-secs = 10
-nanos = 643158348
+secs = 12
+nanos = 427354221
diff --git a/AGENTS.md b/AGENTS.md
index 986b7d8..022bd2e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -252,3 +252,8 @@ never include unrelated or pre-existing user changes. Use a concise conventional
commit message that describes the completed behavior. If a task cannot be
verified or committed, leave it unchecked and report the blocker instead of
combining it with later work.
+
+After every milestone's acceptance criteria and quality gates pass, create an
+annotated Git tag named `milestone-N` on its completion commit. Never move an
+existing milestone tag; add a corrective commit and a documented successor tag
+if a published milestone needs amendment.
diff --git a/README.md b/README.md
index af39712..0b5b51c 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,7 @@ signals, not the probability that AI wrote the content.
- [Documentation index](docs/README.md)
- [Command-line usage and current capabilities](docs/usage.md)
- [Architecture and public library API](docs/architecture.md)
+- [Layered configuration](docs/configuration.md)
- [Development, tests, features, and coverage](docs/development.md)
- [Design decision records](docs/decisions/)
- [Background reading](docs/background.md)
diff --git a/badges/coverage.svg b/badges/coverage.svg
index d8efb10..67b819e 100644
--- a/badges/coverage.svg
+++ b/badges/coverage.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
index 5b169aa..aa9fe74 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,6 +7,8 @@ the details needed to use, embed, and develop John Slop:
and the current formatter/LSP status.
- [Architecture](architecture.md) describes module boundaries, shared domain
values, input safety, and the reusable library facade.
+- [Configuration](configuration.md) documents schema version 1, source
+ precedence, stable-ID merges, validation, and inspection commands.
- [Development](development.md) covers the supported Rust version, feature
matrix, snapshots, coverage, badges, and CI quality gates.
- [Background](background.md) collects external context on observable signs of
diff --git a/docs/architecture.md b/docs/architecture.md
index e33b579..2f9669e 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -35,9 +35,10 @@ The crate root exposes four entry points:
- `analyze_source` returns findings and evidence confidence for UTF-8 text;
- `plan_replacements` returns safe edits against the same source snapshot.
-Configuration files and precedence layers are a later milestone. Keeping these
-operations behind the facade lets those layers evolve without duplicating logic
-across the three binaries.
+`ConfigLoader` applies embedded, user base, named user, explicit file, and CLI
+layers in order. Stable-ID merging and semantic validation happen before a
+configuration reaches analysis. Keeping these operations behind the facade
+avoids duplicating policy across the three binaries.
See [ADR 0001](decisions/0001-core-analysis-contracts.md) for the foundational
contracts and [ADR 0002](decisions/0002-input-policy-and-limits.md) for traversal
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..c5e0b92
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,65 @@
+# 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 `.toml`;
+4. an explicit `--config `;
+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:
+
+```sh
+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`](../assets/config.toml) and
+[`assets/heuristics.toml`](../assets/heuristics.toml).
+
+Replacement and heuristic arrays merge by stable `id`. A partial record changes
+only the supplied fields:
+
+```toml
+[[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:
+
+```sh
+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.
diff --git a/docs/development.md b/docs/development.md
index 2bd1b87..e926cbe 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -36,8 +36,8 @@ Run line coverage with Cargo Tarpaulin:
cargo tarpaulin --config tarpaulin.toml
```
-The configuration enforces a 30% floor. The current suite measured 72.32%
-(196/271 lines) on 2026-09-29. The low floor is intentional while CLI
+The configuration enforces a 30% floor. The current suite measured 73.13%
+(430/588 lines) on 2026-09-29. The low floor is intentional while CLI
subprocesses and future protocol adapters are not attributed consistently by
every backend; the tracked badge still reports the measured result.
@@ -58,3 +58,6 @@ change crosses a binary boundary. Important edge cases include malformed input,
invalid UTF-8, empty text, Unicode byte spans, deterministic ordering, archive
limits, and near misses for detection rules. The detailed expectations and
task-level commit discipline are in [AGENTS.md](../AGENTS.md).
+
+Each completed milestone receives an immutable annotated `milestone-N` Git tag
+after its acceptance criteria and quality gates pass.
diff --git a/docs/usage.md b/docs/usage.md
index f305612..452896e 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -27,6 +27,12 @@ Exit statuses are stable:
Confidence is a summary of observable configured evidence. It is not an
AI-authorship probability.
+Configuration layers can be selected with `--config-name NAME` and `--config
+FILE`; `--max-document-bytes BYTES` is the current highest-precedence input
+override. Use `john-slop config show` to print the resolved TOML and `john-slop
+config paths` to inspect source precedence. See [Configuration](configuration.md)
+for the schema and merge rules.
+
## Supported input policy
Input reads use strict UTF-8 and reject NUL-containing text. They do not follow
diff --git a/src/config.rs b/src/config.rs
index 711d704..992a573 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -1163,6 +1163,13 @@ mod tests {
id = "em-dash"
enabled = false
+[[replacements]]
+id = "right-arrow"
+source = "→"
+replacement = "->"
+rationale = "Use an ASCII arrow in plain text."
+enabled = true
+
[[rules]]
id = "templated-conclusion"
weight = 9.5
@@ -1173,7 +1180,7 @@ weight = 9.5
let config = ConfigLoader::from_paths(paths).load().unwrap();
- assert_eq!(config.replacements.len(), 10);
+ assert_eq!(config.replacements.len(), 11);
let replacement = config
.replacements
.iter()
@@ -1182,6 +1189,7 @@ weight = 9.5
assert!(!replacement.enabled);
assert_eq!(replacement.source, '—');
assert_eq!(replacement.replacement, "-");
+ assert_eq!(config.replacements.last().unwrap().id, "right-arrow");
assert_eq!(config.rules.len(), 6);
let heuristic = config
.rules
@@ -1258,4 +1266,91 @@ weight = 9.5
"john_slop::config::invalid_value"
);
}
+
+ #[test]
+ fn each_file_layer_can_override_embedded_defaults_independently() {
+ let base_dir = tempfile::tempdir().unwrap();
+ std::fs::write(
+ base_dir.path().join("config.toml"),
+ "[thresholds]\nlow = 21\n",
+ )
+ .unwrap();
+ let base = ConfigLoader::from_paths(ConfigPaths::in_directory(
+ base_dir.path().to_owned(),
+ None,
+ None,
+ ))
+ .load()
+ .unwrap();
+ assert_eq!(base.thresholds.low, 21);
+
+ let named_dir = tempfile::tempdir().unwrap();
+ std::fs::write(
+ named_dir.path().join("strict.toml"),
+ "[thresholds]\nlow = 22\n",
+ )
+ .unwrap();
+ let name = "strict".parse::().unwrap();
+ let named = ConfigLoader::from_paths(ConfigPaths::in_directory(
+ named_dir.path().to_owned(),
+ Some(&name),
+ None,
+ ))
+ .load()
+ .unwrap();
+ assert_eq!(named.thresholds.low, 22);
+
+ let explicit_dir = tempfile::tempdir().unwrap();
+ let explicit_path = explicit_dir.path().join("project.toml");
+ std::fs::write(&explicit_path, "[thresholds]\nlow = 23\n").unwrap();
+ let explicit = ConfigLoader::from_paths(ConfigPaths::in_directory(
+ explicit_dir.path().to_owned(),
+ None,
+ Some(explicit_path),
+ ))
+ .load()
+ .unwrap();
+ assert_eq!(explicit.thresholds.low, 23);
+ }
+
+ #[test]
+ fn named_layers_apply_only_when_selected() {
+ let directory = tempfile::tempdir().unwrap();
+ std::fs::write(
+ directory.path().join("strict.toml"),
+ "[thresholds]\nlow = 25\n",
+ )
+ .unwrap();
+
+ let unselected = ConfigLoader::from_paths(ConfigPaths::in_directory(
+ directory.path().to_owned(),
+ None,
+ None,
+ ))
+ .load()
+ .unwrap();
+ let name = "strict".parse::().unwrap();
+ let selected = ConfigLoader::from_paths(ConfigPaths::in_directory(
+ directory.path().to_owned(),
+ Some(&name),
+ None,
+ ))
+ .load()
+ .unwrap();
+
+ assert_eq!(unselected.thresholds.low, 20);
+ assert_eq!(selected.thresholds.low, 25);
+ }
+
+ #[test]
+ fn malformed_toml_is_a_fatal_layer_error() {
+ let directory = tempfile::tempdir().unwrap();
+ let path = directory.path().join("config.toml");
+ std::fs::write(&path, "[input\nmax_document_bytes = 12\n").unwrap();
+ let paths = ConfigPaths::in_directory(directory.path().to_owned(), None, None);
+
+ let error = ConfigLoader::from_paths(paths).load().unwrap_err();
+
+ assert!(matches!(error, ConfigError::Layer(layer) if layer.path == path));
+ }
}
diff --git a/tasks.md b/tasks.md
index 9735e6a..d7fada8 100644
--- a/tasks.md
+++ b/tasks.md
@@ -99,7 +99,7 @@ entry do not discard successful documents.
a `miette` configuration diagnostic.
- [x] Add `john-slop config show` and `john-slop config paths` so precedence is
inspectable; output deterministic TOML or JSON.
-- [ ] Test every layer alone and in combination, including missing optional files,
+- [x] Test every layer alone and in combination, including missing optional files,
malformed TOML, unknown fields, named configs, array semantics, and CLI wins.
Acceptance: installed binaries work without source-tree assets, the resolved