#include "bees-config.h"
+// Version 2 of the built-in configuration schema, and the one under
+// development: new options and changed defaults land here.
+//
+// This file is a delta. It carries only what version 2 states differently
+// from the schema it inherits from -- a new option, a changed default, or a
+// changed comment -- and everything else resolves along the inheritance chain
+// to bees-config-v1.cc, which holds the defaults that reproduce v0.11
+// behaviour. A key that would only repeat what version 1 already says
+// does not belong here: it would be a second copy of a value with nothing
+// holding the two in step. Section headers appear only where this version
+// has something of its own to say, or where one is needed to hold a key
+// that does.
+//
+// So changing an existing default means adding that key here, not editing it
+// in version 1, and a key already listed here is one this version has taken a
+// position on. A key whose value matches version 1 but whose comment does not
+// still belongs here: the comment is part of what a schema states, and it is
+// what --show-config hands the operator.
+//
+// Built-in config comments are a compact option reference. Keep them focused
+// on option semantics, accepted values, defaults, and direct effects. Put use
+// cases, examples, tradeoffs, and background explanation in user docs instead.
+// Keep option names and semantics aligned with docs/config-file.md and parser
+// code when changing configuration behavior.
static const char bees_config_v2[] = R"--v2-config--(
# The [config] section controls config file sources and versioning.
)--v2-config--";
-// Schema version 2 is the one under development: new options and changed
-// defaults land here. bees-config-v1.cc is being frozen at the defaults that
-// reproduce v0.11 behaviour.
+// Inherits from the schema that reproduces v0.11 behaviour; see the file
+// comment above.
static BeesConfig::Register s_reg_config_v2("2", "v0.11", bees_config_v2);