fix(config): name the resolved config, and stop plugin lists shadowing defaults (#166)

A config decides which extractors run and which paths are ignored, so loading the
wrong one does not fail — it analyses something other than what was asked for. Two
behaviours combined to make that silent: lookup falls back to the binary's own
directory, and a list-valued key replaces the built-in list rather than extending
it. An eleven-extractor config beside a `go build` output therefore disabled Rust
for every repository that binary was pointed at, from any directory without a
config of its own: a 780-file Rust repo reported 0 facts, no error, no mention of
Rust anywhere in the log.

- bootstrap.ResolveConfig returns the resolved path alongside the config, and
  NewEngine prints it on every command. check/coverage build their note from
  cfg.SourcePath too — they reported the config they looked FOR, which under the
  fallback was not the one in force.
- The executable-adjacent fallback is restricted to a binary that is not on PATH
  (an unpacked bundle rather than an installed one), and discloses itself.
- config.Load records whether the file listed `extractors:` itself; when it did,
  the engine detects the disabled extractors and warns for any that match the
  repository, recording them as shadowed_extractors in the receipt.
- mcp-arch.yaml and examples/*.yaml no longer declare extractors/explainers/
  renderers. Beyond the reported instance: every example pinned four of the ten
  explainers, so adopters lost the other six, and full.yaml claimed to enable all
  languages while omitting grpc, openapi and python.

`extractors:` still replaces rather than merges — it is the only way to disable an
extractor, and trading a loud omission for a silent inability to turn things off is
the worse bargain. Tests pin the resolution rules, the PATH restriction, the shadow
report, and the absence of plugin lists from every shipped config.

Author: dejo1307

ARCHITECTURE.md

@@ -825,7 +825,13 @@ output:
   max_context_tokens: 16000
 ```
 
-The bundled [`mcp-arch.yaml`](mcp-arch.yaml) ships a much fuller `ignore` list (Android/Gradle, Xcode/SPM, Rails, CI, Docker, env files, …); see it and the per-language configs under [`examples/`](examples/) for ready-made starting points.
+The bundled [`mcp-arch.yaml`](mcp-arch.yaml) ships a much fuller `ignore` list (Android/Gradle, Xcode/SPM, Rails, CI, Docker, env files, …); see it and the per-language configs under [`examples/`](examples/) for ready-made starting points. It deliberately declares **no** `extractors:`, `explainers:` or `renderers:` — see the override rule below.
+
+**Resolution, and why it is announced.** `bootstrap.ResolveConfig` looks for the named path (default `mcp-arch.yaml`) relative to the working directory, then — only when the running binary is *not* on `PATH`, i.e. an unpacked bundle rather than an installed one — beside the executable. Whatever it settles on is printed to stderr by every command (`enola: using config <path>`, or `no mcp-arch.yaml in <cwd>, using built-in defaults`), and the executable-adjacent case says so explicitly.
+
+That line exists because the failure it prevents is silent. A config decides which extractors run and which paths are ignored, so loading the wrong one does not error — it analyses something other than what was asked for. Before the restriction and the announcement, a config sitting beside a `go build` output governed every repository that binary was ever pointed at, from any directory without one of its own; an eleven-extractor list written before the Rust extractor landed turned a 780-file Rust repository into `0 facts`, with no error and no mention of Rust anywhere in the log.
+
+**A list-valued key REPLACES its default; it does not merge.** `yaml.Unmarshal` overwrites the slice, so `extractors:` names the complete set — a config written before an extractor existed disables it permanently, and a disabled extractor is never tried and so never appears in the log. Two things make that visible: a bundled config that names no plugin lists at all, and a warning naming any *excluded* extractor that would have detected the repository (also recorded as `shadowed_extractors` in the snapshot receipt). The semantics are unchanged on purpose — an explicit list is the only way to disable an extractor.
 
 | Field | Description | Default |
 |-------|-------------|---------|

README.md

@@ -119,7 +119,7 @@ enola check --warn-only          # report everything, fail nothing
 
 Not a language model, and not embeddings. enola parses your source with tree-sitter and language-specific extractors, normalizes it into a typed fact model, links it into a directed graph, and runs real graph algorithms over it — Tarjan's SCC for cycles, cycle-safe longest-path for dependency depth, mean+2σ outlier tests for the statistical findings.
 
-That means the same commit yields the same answer, every time. Every snapshot carries a **receipt**: enola's version, the git ref and whether the tree was dirty, the extractors used, and a snapshot ID that's a `sha256` fingerprint of the facts rather than a random UUID. Before trusting a comparison, enola checks the two snapshots were even built the same way — a different extractor set or changed ignore rules makes a diff meaningless, and it says so instead of reporting churn as if it were your change.
+That means the same commit yields the same answer, every time — measured, not asserted: across 30 open-source repositories indexed three times each, all 30 produced a byte-identical snapshot ID and a byte-identical fact file, over 3.9 million facts with zero parse errors ([BENCHMARKS.md](docs/BENCHMARKS.md)). Every snapshot carries a **receipt**: enola's version, the git ref and whether the tree was dirty, the extractors used, and a snapshot ID that's a `sha256` fingerprint of the facts rather than a random UUID. Before trusting a comparison, enola checks the two snapshots were even built the same way — a different extractor set or changed ignore rules makes a diff meaningless, and it says so instead of reporting churn as if it were your change.
 
 Nothing leaves your machine. It's a local binary reading local files.
 
@@ -173,6 +173,8 @@ Framework- and platform-specific detection for each language is described in **[
 ## Learn more
 
 - **[docs/CLI.md](docs/CLI.md)** - setup, every command and flag, the exit codes, and the `--explain` report.
+- **[docs/BENCHMARKS.md](docs/BENCHMARKS.md)** - reproducibility, delta precision, cross-repo coverage and scale, measured on 30 public repositories - including the three defects the run found in enola itself.
+- **[docs/extraction/](docs/extraction/)** - per language, what specific code produces which facts, from committed fixtures - and what each extractor deliberately does not resolve.
 - **[ARCHITECTURE.md](ARCHITECTURE.md)** - the concept, the fact model, the pipeline, the MCP tool reference, and the value model.
 - **[examples/](examples/)** - ready-made per-language and multi-repo configs, plus a pre-commit hook and a CI workflow.
 

cmd/enola/check.go

@@ -41,11 +41,9 @@ type target struct {
 func resolveTarget(arg string) target {
 	cfgPath := "mcp-arch.yaml"
 	repoOverride := ""
-	note := ""
 
 	switch {
 	case arg == "":
-		note = "config " + cfgPath + " (or built-in defaults)"
 	case isDirectory(arg):
 		abs, err := filepath.Abs(arg)
 		if err != nil {
@@ -54,19 +52,28 @@ func resolveTarget(arg string) target {
 		repoOverride = abs
 		if inner := filepath.Join(abs, "mcp-arch.yaml"); fileExists(inner) {
 			cfgPath = inner
-			note = "repo " + abs + " (config " + inner + ")"
-		} else {
-			note = "repo " + abs + " (built-in default config)"
 		}
 	default:
 		cfgPath = arg
-		note = "config " + arg
 	}
 
 	eng, cfg, err := bootstrap.NewEngine(bootstrap.Options{ConfigPath: cfgPath})
 	if err != nil {
 		checkFatal("failed to create engine: %v", err)
 	}
+
+	// The note names the config that was LOADED, not the one that was looked for.
+	// The two differ whenever the lookup falls back — to built-in defaults, or to a
+	// config sitting beside the binary — and a note that reports the intent as
+	// though it were the outcome is worse than none: it is a confirmation of
+	// something nobody checked.
+	note := "built-in default config"
+	if cfg.SourcePath != "" {
+		note = "config " + cfg.SourcePath
+	}
+	if repoOverride != "" {
+		note = "repo " + repoOverride + " (" + note + ")"
+	}
 	if repoOverride != "" {
 		// Repos would otherwise win in RepoPaths and silently ignore the directory the
 		// caller named.

docs/CLI.md

@@ -41,7 +41,18 @@ Because your agent launches enola as a long-lived MCP server process, an upgrade
 
 ### Configuration (optional)
 
-**enola needs no config file.** Every setting has a built-in default, so out of the box it indexes the current repo with all extractors enabled and writes to `.enola/`. A config file (`mcp-arch.yaml`) only *overrides* those defaults - it never adds capability you'd otherwise lack. When enola can't find one it simply prints `warning: …, using defaults` and carries on.
+**enola needs no config file.** Every setting has a built-in default, so out of the box it indexes the current repo with all extractors enabled and writes to `.enola/`. A config file (`mcp-arch.yaml`) only *overrides* those defaults - it never adds capability you'd otherwise lack.
+
+Every command prints the config it resolved, on stderr, before it does anything:
+
+```
+enola: using config /Users/you/src/api/mcp-arch.yaml
+enola: no mcp-arch.yaml in /Users/you/src/api, using built-in defaults
+```
+
+It is worth reading. A config decides which extractors run and which paths are ignored, so the wrong one does not fail - it analyses something other than what you asked for. enola looks in the working directory, then (only for a binary that is *not* on your `PATH`, i.e. an unpacked bundle rather than an installed one) beside the executable; the second case says so explicitly.
+
+Note that a list-valued setting **replaces** its default rather than extending it. That is why the bundled `mcp-arch.yaml` declares no `extractors:`, `explainers:` or `renderers:` - a copied list silently falls behind as new ones ship. Set `extractors:` only to deliberately narrow a run; enola warns when an extractor you excluded would have detected the repository.
 
 The install script installs **only the binary**, by design - it does not place a config file. Grab the bundled one from the repo whenever you want to customize (tune the `ignore` globs, pick a subset of extractors, change the output dir, …):
 

examples/cpp.yaml

@@ -40,13 +40,13 @@ ignore:
   - "**/*.json"
 extractors:
   - cpp
-explainers:
-  - cycles
-  - layers
-  - crossrepo
-  - coverage
-renderers:
-  - llm_context
+# explainers: / renderers: are deliberately absent.
+#
+# A list-valued key REPLACES the built-in list rather than extending it, so naming
+# a subset here silently disables everything that ships beyond it — this file used
+# to pin four explainers, turning off the other six (god-class, hotspots,
+# unused-routes, dependency-depth, exported-surface, complexity-outliers) for anyone
+# who adopted it. Omitting the keys means new plugins arrive automatically.
 output:
   dir: ".enola"
   max_context_tokens: 16000

examples/full.yaml

@@ -4,7 +4,7 @@
 # ignore patterns for every language. Use this as a starting point
 # and remove sections that don't apply to your project.
 #
-# Supported extractors:
+# Supported extractors — all enabled by default, so this file lists none:
 #   - go         (detection: go.mod)
 #   - java       (detection: pom.xml, build.gradle, or .java sources)
 #   - kotlin     (detection: build.gradle.kts or build.gradle with Kotlin/Android)
@@ -14,6 +14,10 @@
 #   - rust       (detection: Cargo.toml)
 #   - cpp        (detection: .cpp/.hpp/... or CMakeLists.txt/Makefile + header)
 #   - php        (detection: composer.json, WordPress markers, or any .php source)
+#   - python     (detection: pyproject.toml, setup.py, requirements.txt, Pipfile,
+#                 or a tool config — pytest.ini/mypy.ini/tox.ini/setup.cfg)
+#   - grpc       (detection: first-party .proto sources)
+#   - openapi    (detection: a YAML/JSON file whose content is an OpenAPI spec)
 
 repo: "."
 ignore:
@@ -97,23 +101,18 @@ ignore:
   - "**/Dockerfile*"
   - "**/.env*"
 
-extractors:
-  - cpp
-  - go
-  - java
-  - kotlin
-  - typescript
-  - swift
-  - ruby
-  - rust
-  - php
-explainers:
-  - cycles
-  - layers
-  - crossrepo
-  - coverage
-renderers:
-  - llm_context
+# extractors: / explainers: / renderers: are deliberately absent.
+#
+# A list-valued key REPLACES the built-in list rather than extending it, so naming
+# a subset here silently disables everything that ships beyond it. Both lists had
+# already fallen behind: `extractors:` claimed to enable every language while
+# omitting grpc, openapi and python, and `explainers:` pinned four of the ten,
+# turning off god-class, hotspots, unused-routes, dependency-depth,
+# exported-surface and complexity-outliers for anyone who adopted this file.
+#
+# The defaults ARE everything, so a config that means "all of it" says nothing at
+# all. Narrow the lists only on purpose, as the per-language examples in this
+# directory do.
 output:
   dir: ".enola"
   max_context_tokens: 16000

examples/go.yaml

@@ -29,13 +29,13 @@ ignore:
   - "**/.env*"
 extractors:
   - go
-explainers:
-  - cycles
-  - layers
-  - crossrepo
-  - coverage
-renderers:
-  - llm_context
+# explainers: / renderers: are deliberately absent.
+#
+# A list-valued key REPLACES the built-in list rather than extending it, so naming
+# a subset here silently disables everything that ships beyond it — this file used
+# to pin four explainers, turning off the other six (god-class, hotspots,
+# unused-routes, dependency-depth, exported-surface, complexity-outliers) for anyone
+# who adopted it. Omitting the keys means new plugins arrive automatically.
 output:
   dir: ".enola"
   max_context_tokens: 16000

examples/kotlin.yaml

@@ -38,13 +38,13 @@ ignore:
   - "**/.env*"
 extractors:
   - kotlin
-explainers:
-  - cycles
-  - layers
-  - crossrepo
-  - coverage
-renderers:
-  - llm_context
+# explainers: / renderers: are deliberately absent.
+#
+# A list-valued key REPLACES the built-in list rather than extending it, so naming
+# a subset here silently disables everything that ships beyond it — this file used
+# to pin four explainers, turning off the other six (god-class, hotspots,
+# unused-routes, dependency-depth, exported-surface, complexity-outliers) for anyone
+# who adopted it. Omitting the keys means new plugins arrive automatically.
 output:
   dir: ".enola"
   max_context_tokens: 16000

examples/multi-repo.yaml

@@ -100,13 +100,13 @@ extractors:
   - typescript
   - swift
   - ruby
-explainers:
-  - cycles
-  - layers
-  - crossrepo
-  - coverage
-renderers:
-  - llm_context
+# explainers: / renderers: are deliberately absent.
+#
+# A list-valued key REPLACES the built-in list rather than extending it, so naming
+# a subset here silently disables everything that ships beyond it — this file used
+# to pin four explainers, turning off the other six (god-class, hotspots,
+# unused-routes, dependency-depth, exported-surface, complexity-outliers) for anyone
+# who adopted it. Omitting the keys means new plugins arrive automatically.
 output:
   dir: ".enola"
   max_context_tokens: 16000

examples/php.yaml

@@ -46,13 +46,13 @@ ignore:
   - "**/*.md"
 extractors:
   - php
-explainers:
-  - cycles
-  - layers
-  - crossrepo
-  - coverage
-renderers:
-  - llm_context
+# explainers: / renderers: are deliberately absent.
+#
+# A list-valued key REPLACES the built-in list rather than extending it, so naming
+# a subset here silently disables everything that ships beyond it — this file used
+# to pin four explainers, turning off the other six (god-class, hotspots,
+# unused-routes, dependency-depth, exported-surface, complexity-outliers) for anyone
+# who adopted it. Omitting the keys means new plugins arrive automatically.
 output:
   dir: ".enola"
   max_context_tokens: 16000