docs: say what --show-builtin-config resolves

The description said the command writes "the built-in configuration for
VERSION", which reads as the contents of the schema file with that name.
It is not: a schema states only the keys it changes, so the command
flattens the whole inheritance chain and prints what the version resolves
to.

The distinction is the one a reader is most likely to get wrong, because
the surprising half looks like a bug -- asking for version 1 lists
options version 1 has never heard of.  Say why that is right (a daemon
pinned to that version resolves them too), and say what happens where the
versions disagree (the selected version's value wins), with the concrete
case.

Assisted-by: Claude-Code:claude-opus-5

diff --git a/docs/options.md b/docs/options.md
index a9a083597910d03b7031736e131232c41f7bfb4c..133b7c714285647d9b7485c33fc673c8d0421dfe 100644 (file)
--- a/docs/options.md
+++ b/docs/options.md
@@ -114,6 +114,19 @@ space used--until the read-only snapshots are deleted.
   `VERSION` may be a numeric config version accepted by this bees build, the
   alias `CURRENT` or `STABLE`, or a release alias such as `v0.11`.
 
+  The output is what `VERSION` *resolves to*, not the contents of the schema
+  file that carries its name.  A schema states only the keys it changes, and
+  everything else comes from the rest of the inheritance chain, so the dump
+  is the whole chain flattened: every key any version defines, each with the
+  value `VERSION` resolves for it.
+
+  That means asking for an older version still lists options added after it,
+  which is the point — a daemon pinned to that version resolves them too,
+  each to the value it was introduced with.  Where the selected version has
+  an opinion of its own, that opinion wins: on a build where version 2
+  changes `state.point.defer` to `yes`, `--show-builtin-config 1` lists the
+  key with version 1's `no`, alongside every option version 2 added.
+
   This command does not load a filesystem, global config file, local config
   file, environment-derived paths, or `--config` / `--option` input.  It is
   intended for offline inspection of the compiled-in defaults.