René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"agent: tool config specs should only manage the tool's own config files","articleBody":"## What happened\n\nWhen 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.\n\n## Root cause\n\nThe 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.\n\n## Generalised principle\n\nWhen 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.\n\n## Resolution\n\nRemoved `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.\n\n## Follow-up\n\nNone.","author":{"url":"https://github.com/nathanjmcdougall","@type":"Person","name":"nathanjmcdougall"},"datePublished":"2026-04-07T18:41:24.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/1867/usethis-python/issues/1867"}