Generate the settings reference from the schema

Every other form of documentation here has drifted at least once today:
search routing that pointed at a page not containing the setting, a
contract that pinned the bug the same commit fixed, and a comment in
shell.qml that failed to stop me making the exact mistake it described.
Prose describing 127 settings would drift the day after it was written.

So docs/settings.md is generated, and a contract fails the moment the
committed copy stops matching the schema. The document cannot be wrong
for longer than it takes to run the suite.

It reads the schema by parsing rather than importing, since there is no
QML interpreter here and requiring a compositor to build documentation
would be worse. That parser is the risk, so it FAILS LOUDLY: if it stops
recognising the file it exits non-zero with the reason and writes
nothing, because a partial reference is worse than a stale one -- stale
is caught by --check, partial reads as complete. Verified: with the
entry pattern broken it reports "only 0 entries parsed" and leaves the
committed file untouched.

The contract also proves --check actually compares content, by appending
a line and confirming it fails, rather than trusting a command that
returns success to mean anything.

Claude-Session: https://claude.ai/code/session_01BRvzt4H8XXLPVH5MyYdk9L

tests/quickshell/settings-docs-contract.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+
+# The settings reference is generated, and must not be stale.
+#
+# Every other kind of documentation here has drifted at least once: routing that
+# pointed at a page not containing the setting, contracts that pinned the bug
+# they were meant to prevent, a comment that failed to stop the person who read
+# it from making the exact mistake it described. Prose describing 127 settings
+# would drift the day after it was written.
+#
+# So docs/settings.md is generated from the schema, and this fails the moment
+# the committed copy stops matching. That is the whole mechanism: the document
+# cannot be wrong for longer than it takes to run the suite.
+
+set -uo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+generator="$repo_dir/config/dot/quickshell/scripts/panama-settings-docs"
+doc="$repo_dir/docs/settings.md"
+
+fail() {
+    printf 'settings docs contract: %s\n' "$1" >&2
+    exit 1
+}
+
+[[ -x "$generator" ]] || fail 'the generator is missing or not executable'
+
+"$generator" --check || fail 'docs/settings.md is stale -- run quickshell/scripts/panama-settings-docs and commit the result'
+
+# A generator that silently emitted nothing would also pass --check against an
+# equally empty file, so the output is checked for substance too.
+[[ -s "$doc" ]] || fail 'docs/settings.md is empty'
+
+settings="$(grep -c '^| \*\*' "$doc")"
+schema_keys="$(grep -c 'key: "' "$repo_dir/config/dot/quickshell/config/PreferenceSchema.qml")"
+
+# Internal keys are deliberately omitted, so the document is smaller than the
+# schema -- but not by much. A large gap means the reader stopped recognising
+# entries and quietly documented a fraction of them.
+(( settings > schema_keys * 8 / 10 )) \
+    || fail "the reference documents only $settings of $schema_keys schema keys, which suggests the generator stopped parsing partway"
+
+# The compositor-backed settings are the ones worth naming precisely, since
+# that is the string someone would search the Hyprland docs for.
+grep -q 'cursor:zoom_factor' "$doc" \
+    || fail 'compositor option names are missing from the reference'
+
+# A stale copy must be detectable, not merely regenerable. Prove the check
+# actually compares content rather than always returning success.
+scratch="$(mktemp -d /tmp/panama-docs.XXXXXX)"
+trap 'rm -rf "$scratch"' EXIT
+cp "$doc" "$scratch/settings.md"
+printf '\n<!-- drift -->\n' >>"$doc"
+if "$generator" --check >/dev/null 2>&1; then
+    cp "$scratch/settings.md" "$doc"
+    fail '--check reported success on a modified file, so staleness would never be caught'
+fi
+cp "$scratch/settings.md" "$doc"
+
+printf 'settings docs contract: PASS (%d settings documented)\n' "$settings"