config-contract

Config Contract

Config & Customization Contract

Domain configuration composes fastmcp_pvl_core.ServerConfig inside your domain config class (see src/markdown_vault_mcp/config.py). Add domain fields between the CONFIG-FIELDS-START / CONFIG-FIELDS-END sentinels, populate them in from_env between the CONFIG-FROM-ENV-START / CONFIG-FROM-ENV-END sentinels, and enforce their invariants in __post_init__ between the CONFIG-VALIDATE-START / CONFIG-VALIDATE-END sentinels. Validation belongs in __post_init__ rather than from_env because it then also covers a direct ProjectConfig(field=...); env_float / env_int bounds check only the env-sourced value, are inclusive-only, and cannot express cross-field rules. The dataclass is frozen — read fields, don't assign (use object.__setattr__ if a field must be normalised). Never inherit from ServerConfig; always compose.

Env var prefix is MARKDOWN_VAULT_MCP_ — all env reads go through fastmcp_pvl_core.env(_ENV_PREFIX, "SUFFIX", default) so naming stays consistent.

• Domain CLI subcommands go in the # DOMAIN-COMMANDS-START / -END block in cli.py (like CONFIG-FIELDS in config.py). Register them as @app.command() and use function-local imports for domain modules. The block is preserved across copier update.

Config wizard

docs/javascripts/config-wizard/wizard-spec.json drives the guided-setup page. It is generated, produced by scripts/gen_config_surface.py on every copier copy/copier update and re-verified by scripts/gen_config_surface.py --check in CI — never hand-edit it. The runtime (wizard.js, generators.js, wizard-spec-schema.json, the generic tests) is template-owned and re-rendered the same way it always was.

To change what the wizard asks:

• A domain setting your project reads — give its ProjectConfig field (between the CONFIG-FIELDS-START/-END sentinels in config.py) a metadata={"help": ..., "tags": (...)}. The generator's AST scan discovers it from there; no wizard-spec edits needed.
• A var the scan cannot see (a deprecated alias no longer read inside ProjectConfig.from_env, or something read outside it entirely) — declare it in config-presentation.domain.yml instead.
• A path the container needs mounted — add dockerVolume to the field's wizard hint: metadata={"help": ..., "tags": (...), "wizard": {"group": "Storage", "dockerVolume": "/data/corpus"}}. When the user supplies a host path, the wizard's Docker and Compose output emits a -v <that answer>:/data/corpus bind mount and sets the var to the container path, instead of an -e naming a host path the container cannot reach. Leaving the field blank emits neither — no mount and no override — so an optional path the user skipped never produces a command pointing at a file that was never mounted. Use dockerPath instead for a fixed location on the state volume that the server creates itself: it substitutes the path when the var is already present and never adds a mount. The two are mutually exclusive and both must be absolute; the generator rejects a violation by name.
• Coverage is enforced, not automatic — the generator fails loudly (SystemExit, naming the var and its tags) if a collected Var's tags match no env-file section, rather than silently dropping it from every generated file. Giving a domain field a tag no section lists is a config-presentation bug, and this catches it at generation time instead of shipping an undocumented var. There is, however, no orphan check: a stale or mistaken entry in config-presentation.domain.yml that nothing actually reads will generate into the wizard and env files anyway. Keep that file's contents matched to real reads yourself.