> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whyfile.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring whyfile — whyfile.config.json

> The checked-in artifact that controls docs/records defaults and the audit panel's convergence policy.

## Configuring whyfile: the `whyfile.config.json` file

Every repo has a Makefile, a Dockerfile, a lockfile. This tool adds the missing one: a checked-in
`whyfile.config.json` at repo root holds this repo's own contract — where intent lives, and how strict the
audit panel is — as a small hand-edited JSON file instead of a code change. Missing entirely is a
no-op: every field falls back to today's hardcoded default, byte-for-byte.

```json theme={null}
{
  "_about": "This repo's intent contract: config + policy + pointers, not a copy of the graph.",
  "intent_sources": { "docs": "docs/", "records": ["docs/adr"] },
  "convergence": { "structural": 3, "sharpen": 2, "note": 1 }
}
```

* **`intent_sources.docs`** / **`intent_sources.records`** — the reconstruct pass's `--docs`
  default and the decision-record ingest directories, so a whole team shares one source of truth
  without repeating `--docs`/`--records` on every invocation. An explicit CLI flag still wins over
  the whyfile.config.json.
* **`convergence`** — the audit panel's dispute thresholds ([Audit](gates.md#audit-hostile-enumeration-panel--convergence-gate)
  in Gates): `structural` refutations auto-dispute, `sharpen` and `note` stay advisory. Tune this
  once you've measured the panel (see [Panel evaluation](../adr/0030-panel-evaluation-harness.md)) —
  never hand-picked without evidence.

A malformed contract (unknown key, wrong type, or thresholds that violate \`structural >= sharpen

> \= note >= 1`) fails loud rather than being silently ignored — a committed contract nobody reads
> is the exact dishonesty this tool exists to catch elsewhere. `whyfile --doctor` reports whether a
> whyfile.config.json is present and what it resolves to. This repo's own [`whyfile.config.json\`]\(../../whyfile.config.json) is the worked example. See
> [ADR-0029](../adr/0029-whyfile-artifact.md).

### Seeing what this actually captures

`docs/decisions/` holds this repo's everyday decision records (see its own `README.md` for the
full open → resolved → promoted lifecycle). For a real, concrete example of a human overriding an
agent's recommendation, read
[`keep-the-active-wrapper-deferred-the-passive-channel-is-suff.md`](../decisions/keep-the-active-wrapper-deferred-the-passive-channel-is-suff.md).
For the artifact rename this file itself just went through, see
[`rename-whyfile-artifact-to-whyfile-config-json.md`](../decisions/rename-whyfile-artifact-to-whyfile-config-json.md).