What happened

When dogfooding usethis tool zensical in a project that already had a mkdocs.yml with content, zensical serve failed with "Missing required setting: site_name" because zensical.toml was created empty.

Root cause

The ZensicalToolSpec config spec listed both ZensicalTOMLManager and MkDocsYMLManager as file managers with first_content resolution. When an existing mkdocs.yml had content, the resolution algorithm selected mkdocs.yml as the active file manager. Since mkdocs.yml already contained the required settings, add_configs() was a no-op — and zensical.toml (which had been created empty via .touch()) was never populated. The zensical CLI then read the empty zensical.toml and failed.

Generalised principle

When defining a tool's config spec, only include file managers for config files that the tool itself reads and writes. Do not include another tool's config file as a managed file manager unless the current tool genuinely reads from that file at runtime. Sharing config file managers across tool specs creates subtle bugs when the resolution algorithm selects a foreign config file and skips writing to the tool's own config file.

Resolution

Removed MkDocsYMLManager and its associated config entries from ZensicalToolSpec.config_spec(). The Zensical tool now only manages zensical.toml. Updated the TestMkDocsYMLFallback test to verify that zensical.toml receives config even when mkdocs.yml is present.

Follow-up

None.