01 · Defaults
Start without a file
With no mcp-arch.yaml, Enola analyzes the current repository, detects applicable extractors, uses its built-in ignore rules, and writes persistent artifacts to .enola/. A configuration file overrides defaults; it does not unlock additional analysis.
02 · Configure
Choose what to override
| Area | Configure it when |
|---|---|
| Repository | The default repository is not the process working directory. |
| Ignore rules | Generated, vendored, fixture, or build-output paths should not enter the graph. |
| Extractors | You need to enable or restrict language and framework extraction explicitly. |
| Providers | An external analyzer should add facts Enola does not extract itself. |
| Output | Snapshot artifacts must be written somewhere other than .enola/. |
| Cluster | The same set of repositories must be composed reproducibly across machines or CI jobs. |
| Intent | You want Enola to compare expected architectural boundaries with relationships found in the code. |
03 · Template
Use the maintained example
curl -fsSL https://raw.githubusercontent.com/enola-labs/enola/main/mcp-arch.yaml -o mcp-arch.yaml
The repository’s examples directory contains language-specific and multi-repo starting points. examples/full.yaml documents every available field.
04 · Use
Pass the file only when needed
An MCP registration may pass a configuration path after the enola command. Without one, the server uses built-in defaults. The configured repository is only the default: an agent can still pass another repo_path to generate_snapshot.
claude mcp add enola enola /absolute/path/to/mcp-arch.yaml
05 · Comparability
Read the receipt with the verdict
Enola records extractor, provider, and ignore configuration in the snapshot receipt. If only the producer set changes, Enola grades their shared facts and marks the result as partial. Changes that affect fact identity, such as the Enola version, repository, or ignore configuration, remain non-comparable.
06 · Troubleshooting
Common setup problems
| Symptom | Check |
|---|---|
| enola is not found | Ensure ~/.local/bin is on PATH, then restart the MCP client. |
| The MCP client cannot connect | Run enola --status and verify the client registration uses the local enola command. |
| A large first snapshot times out | Increase the client’s MCP tool timeout or pre-generate once with enola --generate; later runs can reuse cached extraction. |
| A check returns code 3 | The snapshots are not comparable. Review the receipt and pin a fresh baseline with the current extraction settings. |
| Hooks appear inactive | Run enola doctor; Codex hooks also require one-time approval through /hooks. |
07 · Full reference
See every configuration field
For authoritative field names, defaults, and extractor-specific options, read ARCHITECTURE.md and examples/full.yaml.