feat(config): unify all user choices into one canonical mios.toml dotfile

Kabuki94 · Kabuki94 · commit 82a177951eeb · 2026-05-03T15:08:39.000-04:00
Single source of user truth across the entire stack
====================================================
Every script in mios.git and mios-bootstrap.git that needs a username,
hostname, base image, AI endpoint, flatpak list, profile features, or
free-form env var now resolves through ONE file with three layers:

   /usr/share/mios/mios.toml      vendor defaults     (this commit -- new)
   /etc/mios/mios.toml            host overlay        (bootstrap-staged)
   ~/.config/mios/mios.toml       per-user overlay    (XDG)

The user's editable canonical copy lives at mios-bootstrap.git/mios.toml
(repo root). Higher layers shadow lower layers field-by-field; user-set
fields supersede defaults.

UNIFIED SCHEMA
==============
The two pre-existing schemas (lightweight [user]/[image]/[build] in
~/.config/mios/mios.toml read by userenv.sh, vs. rich [identity]/
[locale]/[auth]/[network]/[ai]/[desktop]/[image]/[bootstrap]/[quadlets]
in profile.toml read by bootstrap install.sh) are folded into ONE
schema -- the rich one. mios.toml now covers all of:

  [identity]         username, fullname, hostname, shell, groups
  [locale]           timezone, keyboard_layout, language
  [auth]             ssh_key_action, password_policy, secrets refs
  [network]          firewalld_default_zone, allow_ssh/cockpit/libvirt_bridge
  [ai]               endpoint, model, embed_model, api_key,
                     enable_ollama/localai, mcp_registry, system_prompt_file
  [desktop]          session, color_scheme, flatpaks
  [image]            ref, branch, base, bib, name, tag, local_tag
  [bootstrap]        mode, mios_repo, bootstrap_repo, install_packages,
                     reboot_on_finish
  [profile]          role, features
  [quadlets.enable]  per-Quadlet first-boot enable flags
  [env]              free-form KEY = VALUE exported verbatim

NEW VENDOR DEFAULTS: usr/share/mios/mios.toml
=============================================
Byte-identical to mios-bootstrap.git/mios.toml; ships in the image as
the lowest layer. The previous usr/share/mios/profile.toml is left in
place untouched so legacy install paths keep working.

UPGRADED RESOLVER: tools/lib/userenv.sh
=======================================
- Reads three TOML layers via Python tomllib + deep-merge.
- Expanded MIOS_* keymap (39 typed slots) covering every section.field
  in the unified schema, plus legacy aliases ([user]/[build]/
  [flatpaks].install) so older user files keep resolving.
- Free-form [env] table still exported verbatim.
- Legacy split files (env.toml/images.toml/build.toml/flatpaks.list/
  bare 'env') now read only when no mios.toml exists at any layer.

UPDATED ENTRY POINT
===================
- Justfile, install scripts, all entry-point scripts continue to source
  tools/lib/userenv.sh; no caller-side changes needed.

DOCUMENTATION
=============
- AGREEMENTS.md gains a new section 8 (single-source-of-user-truth)
  documenting the three-layer overlay, the canonical edit path
  (mios-bootstrap.git/mios.toml), and the per-user re-init workflow.
diff --git a/AGREEMENTS.md b/AGREEMENTS.md
@@ -154,7 +154,40 @@ console interaction. Operators who want a hard gate can wrap any of
 the entry points in `MIOS_REQUIRE_AGREEMENT_ACK=1 ./entrypoint.sh`
 and supply the corresponding handler in their wrapper.
 
-## 8. Pointers
+## 8. Single canonical user-config dotfile
+
+There is **one** file that holds every user choice (account, hostname,
+groups, locale, auth policy, network posture, AI endpoint and model,
+desktop session, flatpak picks, base image refs, build args, profile
+features, free-form env vars, per-Quadlet enable flags). That file is
+`mios.toml`, present in three layers:
+
+| Layer | Path | Owned by | Mutability |
+|---|---|---|---|
+| Vendor | `/usr/share/mios/mios.toml` | `mios.git` | image-immutable |
+| Host | `/etc/mios/mios.toml` | bootstrap (staged) | admin-editable |
+| Per-user | `~/.config/mios/mios.toml` | per Linux user | user-editable |
+
+The user's editable canonical copy in the bootstrap repository lives at
+`mios-bootstrap.git/mios.toml` (repo root). Bootstrap's `install.sh`
+stages it to `/etc/mios/mios.toml` at install time; the per-user copy
+is seeded from `/etc/skel/.config/mios/mios.toml` on `useradd -m`.
+
+Every script that needs a value -- in `mios.git`, `mios-bootstrap.git`,
+the deployed image's `usr/bin/mios` CLI, the `Justfile`, the entry-point
+scripts -- resolves through `tools/lib/userenv.sh` (in `mios.git`),
+which deep-merges the three layers in order (vendor → host → user) and
+exports `MIOS_*` environment variables plus a verbatim `[env]` table.
+Higher layers shadow lower layers field-by-field; user-set fields
+supersede defaults.
+
+To change anything globally for your deployment, edit
+`mios-bootstrap.git/mios.toml` once and re-run `bootstrap.sh` /
+`install.sh`. To change anything just for yourself on a deployed host,
+edit `~/.config/mios/mios.toml` and run `just init-user-space` (or
+re-source `tools/lib/userenv.sh` in your shell).
+
+## 9. Pointers
 
 - [`LICENSE`](./LICENSE) -- Apache-2.0 main license
 - [`LICENSES.md`](./LICENSES.md) -- bundled-component license inventory
diff --git a/tools/lib/userenv.sh b/tools/lib/userenv.sh
@@ -1,81 +1,111 @@
 #!/usr/bin/env bash
 # tools/lib/userenv.sh -- read the unified 'MiOS' user config and export
-# MIOS_* environment variables. Sourced by Justfile, /etc/profile.d, and
-# any tool that needs the user-overridden values.
+# MIOS_* environment variables. Sourced by Justfile, /etc/profile.d, every
+# entry-point script, and any tool that needs the user-overridden values.
 #
-# Single source of user truth: ~/.config/mios/mios.toml
-#   [user]      identity
-#   [image]     base/builder/registry refs
-#   [build]     local tag
-#   [flatpaks]  array of refs
-#   [ai]        model, endpoint, key, optional system_prompt_file
-#   [profile]   role + features (replaces ~/.config/mios/profile.toml)
-#   [env]       free-form KEY = "VALUE" exports (replaces ~/.config/mios/env)
+# THERE IS ONE CANONICAL FILE PATH PER LAYER. Higher layers shadow lower
+# layers field-by-field; the user-edit copy lives in mios-bootstrap and is
+# staged into /etc/mios/mios.toml at install time.
 #
-# Resolution order (first non-empty wins):
-#   1. ~/.config/mios/mios.toml          (user, unified)
-#   2. /etc/mios/install.env             (host, written by Windows installer)
-#   3. /etc/mios/env.d/*.env             (admin drop-ins, alphabetical)
-#   4. /usr/share/mios/env.defaults      (vendor)
+#   1. /usr/share/mios/mios.toml   (vendor defaults; baked into image)        lowest
+#   2. /etc/mios/mios.toml         (host-local; bootstrap-staged)
+#   3. ~/.config/mios/mios.toml    (per-user; XDG)                            highest
 #
-# Backwards-compat: if mios.toml is absent the legacy split files
-# (env.toml / images.toml / build.toml / flatpaks.list / profile.toml /
-# the bare `env` file) are still read. `just init-user-space` migrates them.
+# Schema is the same in all three layers (TOML 1.0; section names below).
+# Resolution mode: deep merge by section.field. The Python helper below
+# reads each layer in order and writes one consolidated set of MIOS_*
+# exports back to the calling shell.
+#
+# Section -> MIOS_* env mapping (typed slots; non-typed fields can still
+# be reached via the [env] table for free-form injection):
+#
+#   [identity]    .username/.fullname/.hostname/.shell/.groups
+#                 -> MIOS_USER, MIOS_USER_FULLNAME, MIOS_HOSTNAME,
+#                    MIOS_USER_SHELL, MIOS_USER_GROUPS (CSV)
+#   [locale]      .timezone/.keyboard_layout/.language
+#                 -> MIOS_TIMEZONE, MIOS_KEYBOARD, MIOS_LOCALE
+#   [auth]        .ssh_key_action/.password_policy
+#                 -> MIOS_SSH_KEY_ACTION, MIOS_PASSWORD_POLICY
+#   [network]     .firewalld_default_zone
+#                 -> MIOS_FIREWALLD_ZONE
+#   [ai]          .endpoint/.model/.embed_model/.api_key/.system_prompt_file/.mcp_registry
+#                 -> MIOS_AI_ENDPOINT, MIOS_AI_MODEL, MIOS_AI_EMBED_MODEL,
+#                    MIOS_AI_KEY, MIOS_SYSTEM_PROMPT_FILE, MIOS_MCP_REGISTRY
+#   [desktop]     .session/.color_scheme/.flatpaks
+#                 -> MIOS_DESKTOP_SESSION, MIOS_COLOR_SCHEME,
+#                    MIOS_FLATPAKS (CSV; consumed by Containerfile build arg)
+#   [image]       .ref/.branch/.base/.bib/.name/.tag/.local_tag
+#                 -> MIOS_IMAGE_REF, MIOS_BRANCH, MIOS_BASE_IMAGE,
+#                    MIOS_BIB_IMAGE, MIOS_IMAGE_NAME, MIOS_IMAGE_TAG,
+#                    MIOS_LOCAL_TAG
+#   [bootstrap]   .mode/.mios_repo/.bootstrap_repo
+#                 -> MIOS_BOOTSTRAP_MODE, MIOS_REPO_URL, MIOS_BOOTSTRAP_REPO_URL
+#   [profile]     .role/.features
+#                 -> MIOS_PROFILE_ROLE, MIOS_PROFILE_FEATURES (CSV)
+#   [env]         arbitrary KEY = "VALUE" pairs                exported verbatim
+#
+# Backwards compat:
+#   - The legacy lightweight schema ([user]/[build]/[flatpaks].install) is
+#     still understood as a fallback when [identity]/[image]/[desktop] are
+#     absent. 'just init-user-space' migrates the legacy split files.
+#   - The legacy split files (env.toml, images.toml, build.toml,
+#     flatpaks.list, the bare 'env' file) are still read when no
+#     mios.toml is present in any layer.
 #
 # Usage: source ./tools/lib/userenv.sh
 # Note: must be sourced (not executed) to affect the calling shell.
 
+MIOS_VENDOR_TOML="${MIOS_VENDOR_TOML:-/usr/share/mios/mios.toml}"
+MIOS_HOST_TOML="${MIOS_HOST_TOML:-/etc/mios/mios.toml}"
 MIOS_CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/mios"
-MIOS_UNIFIED_TOML="${MIOS_CONFIG_DIR}/mios.toml"
+MIOS_USER_TOML="${MIOS_CONFIG_DIR}/mios.toml"
 MIOS_VENDOR_DEFAULTS="${MIOS_VENDOR_DEFAULTS:-/usr/share/mios/env.defaults}"
 
-# Typed-slot map: TOML "section.field" -> MIOS_* env var name.
-# Keep aligned with usr/share/mios/mios.toml.example.
-_mios_keymap=(
-    "user.name=MIOS_USER"
-    "user.hostname=MIOS_HOSTNAME"
-    "image.base=MIOS_BASE_IMAGE"
-    "image.bib=MIOS_BIB_IMAGE"
-    "image.name=MIOS_IMAGE_NAME"
-    "image.tag=MIOS_IMAGE_TAG"
-    "build.local_tag=MIOS_LOCAL_TAG"
-    "ai.model=MIOS_AI_MODEL"
-    "ai.endpoint=MIOS_AI_ENDPOINT"
-    "ai.key=MIOS_AI_KEY"
-    "ai.system_prompt_file=MIOS_SYSTEM_PROMPT_FILE"
-    "profile.role=MIOS_PROFILE_ROLE"
-)
-
-# 1. Vendor defaults (lowest priority). Shell-format KEY="VALUE".
+# 0. Vendor env-defaults (lowest priority, shell-format KEY="VALUE" file).
+# Surfaces port numbers, paths, and infrastructure constants that don't
+# belong in the TOML schema.
 if [[ -f "$MIOS_VENDOR_DEFAULTS" ]]; then
     set -a
     # shellcheck disable=SC1090
     source "$MIOS_VENDOR_DEFAULTS"
     set +a
 fi
 
-# 2. Unified mios.toml -- highest priority. Use python tomllib (3.11+ stdlib).
-_mios_load_toml() {
-    local toml="$1"
-    [[ -f "$toml" ]] || return 0
+# 1. TOML overlay (vendor -> host -> per-user). Use python tomllib (3.11+
+# stdlib; tomli fallback for older). The Python block prints shell-safe
+# 'export' lines that the surrounding shell evals.
+_mios_load_unified() {
+    local layers=("$MIOS_VENDOR_TOML" "$MIOS_HOST_TOML" "$MIOS_USER_TOML")
     command -v python3 >/dev/null 2>&1 || return 0
     local exports
-    exports=$(MIOS_TOML="$toml" python3 - "${_mios_keymap[@]}" <<'PY'
-import os, sys, shlex
+    exports=$(MIOS_LAYERS="${layers[*]}" python3 - <<'PY'
+import os, sys, shlex, re
 try:
     import tomllib
 except ImportError:
     try:
         import tomli as tomllib
     except ImportError:
         sys.exit(0)
-path = os.environ["MIOS_TOML"]
-try:
-    with open(path, "rb") as f:
-        data = tomllib.load(f)
-except Exception as e:
-    sys.stderr.write(f"userenv: failed to parse {path}: {e}\n")
-    sys.exit(0)
+
+layers = os.environ["MIOS_LAYERS"].split()
+
+def deep_merge(dst, src):
+    for k, v in src.items():
+        if isinstance(v, dict) and isinstance(dst.get(k), dict):
+            deep_merge(dst[k], v)
+        else:
+            dst[k] = v
+
+merged = {}
+for path in layers:
+    if not path or not os.path.isfile(path):
+        continue
+    try:
+        with open(path, "rb") as f:
+            deep_merge(merged, tomllib.load(f))
+    except Exception as e:
+        sys.stderr.write(f"userenv: failed to parse {path}: {e}\n")
 
 def get(d, dotted):
     for p in dotted.split("."):
@@ -84,31 +114,68 @@ def get(d, dotted):
         d = d[p]
     return d
 
-# Typed slots
-for arg in sys.argv[1:]:
-    dotted, env = arg.split("=", 1)
-    v = get(data, dotted)
+# Typed slot map. Pairs of "section.field=ENV_VAR".
+slots = [
+    # identity
+    ("identity.username",       "MIOS_USER"),
+    ("identity.fullname",       "MIOS_USER_FULLNAME"),
+    ("identity.hostname",       "MIOS_HOSTNAME"),
+    ("identity.shell",          "MIOS_USER_SHELL"),
+    ("identity.groups",         "MIOS_USER_GROUPS"),
+    # locale
+    ("locale.timezone",         "MIOS_TIMEZONE"),
+    ("locale.keyboard_layout",  "MIOS_KEYBOARD"),
+    ("locale.language",         "MIOS_LOCALE"),
+    # auth
+    ("auth.ssh_key_action",     "MIOS_SSH_KEY_ACTION"),
+    ("auth.password_policy",    "MIOS_PASSWORD_POLICY"),
+    # network
+    ("network.firewalld_default_zone", "MIOS_FIREWALLD_ZONE"),
+    # ai
+    ("ai.endpoint",             "MIOS_AI_ENDPOINT"),
+    ("ai.model",                "MIOS_AI_MODEL"),
+    ("ai.embed_model",          "MIOS_AI_EMBED_MODEL"),
+    ("ai.api_key",              "MIOS_AI_KEY"),
+    ("ai.system_prompt_file",   "MIOS_SYSTEM_PROMPT_FILE"),
+    ("ai.mcp_registry",         "MIOS_MCP_REGISTRY"),
+    # desktop
+    ("desktop.session",         "MIOS_DESKTOP_SESSION"),
+    ("desktop.color_scheme",    "MIOS_COLOR_SCHEME"),
+    ("desktop.flatpaks",        "MIOS_FLATPAKS"),
+    # image
+    ("image.ref",               "MIOS_IMAGE_REF"),
+    ("image.branch",            "MIOS_BRANCH"),
+    ("image.base",              "MIOS_BASE_IMAGE"),
+    ("image.bib",               "MIOS_BIB_IMAGE"),
+    ("image.name",              "MIOS_IMAGE_NAME"),
+    ("image.tag",               "MIOS_IMAGE_TAG"),
+    ("image.local_tag",         "MIOS_LOCAL_TAG"),
+    # bootstrap
+    ("bootstrap.mode",          "MIOS_BOOTSTRAP_MODE"),
+    ("bootstrap.mios_repo",     "MIOS_REPO_URL"),
+    ("bootstrap.bootstrap_repo","MIOS_BOOTSTRAP_REPO_URL"),
+    # profile
+    ("profile.role",            "MIOS_PROFILE_ROLE"),
+    ("profile.features",        "MIOS_PROFILE_FEATURES"),
+    # legacy/lightweight aliases (keep older mios.toml drafts working)
+    ("user.name",               "MIOS_USER"),
+    ("user.hostname",           "MIOS_HOSTNAME"),
+    ("build.local_tag",         "MIOS_LOCAL_TAG"),
+    ("ai.key",                  "MIOS_AI_KEY"),
+    ("flatpaks.install",        "MIOS_FLATPAKS"),
+]
+
+for dotted, env in slots:
+    v = get(merged, dotted)
     if v is None or v == "":
         continue
     if isinstance(v, list):
         v = ",".join(str(x) for x in v)
     print(f"export {env}={shlex.quote(str(v))}")
 
-# Flatpaks list -> MIOS_FLATPAKS
-fl = get(data, "flatpaks.install")
-if isinstance(fl, list) and fl:
-    print(f"export MIOS_FLATPAKS={shlex.quote(','.join(str(x) for x in fl))}")
-
-# Profile features list -> MIOS_PROFILE_FEATURES (comma-joined)
-pf = get(data, "profile.features")
-if isinstance(pf, list) and pf:
-    print(f"export MIOS_PROFILE_FEATURES={shlex.quote(','.join(str(x) for x in pf))}")
-
-# [env] table -> export each key=value verbatim. Keys must match
-# POSIX env-var rules ([A-Za-z_][A-Za-z0-9_]*); silently skip anything else
-# rather than emit an export line bash will error on.
-import re
-ev = data.get("env") if isinstance(data.get("env"), dict) else {}
+# Free-form [env] table: arbitrary KEY=VALUE exports. POSIX-compliant
+# names only; silently skip otherwise so 'eval' below doesn't choke.
+ev = merged.get("env") if isinstance(merged.get("env"), dict) else {}
 for k, v in ev.items():
     if not re.match(r'^[A-Za-z_][A-Za-z0-9_]*$', k):
         sys.stderr.write(f"userenv: skipping invalid [env] key: {k!r}\n")
@@ -122,10 +189,12 @@ PY
     )
     [[ -n "$exports" ]] && eval "$exports"
 }
-_mios_load_toml "$MIOS_UNIFIED_TOML"
+_mios_load_unified
 
-# 3. Backwards compat: if mios.toml is absent, fall back to the legacy split
-# files. Each is shallow KEY = "VALUE" (no sections), so a regex grep works.
+# 2. Backwards-compat: legacy split files (per-user only). Read only when
+# none of the three TOML layers contain a [identity] or [user] section --
+# i.e., the user is on a pre-unified-schema deployment. Each is shallow
+# KEY="VALUE", grep-friendly.
 _mios_legacy_get() {
     local file="$1" key="$2"
     grep -E "^${key}\s*=" "$file" 2>/dev/null \
@@ -134,7 +203,7 @@ _mios_legacy_get() {
         | tr -d '"' || true
 }
 
-if [[ ! -f "$MIOS_UNIFIED_TOML" ]]; then
+if [[ -z "${MIOS_USER:-}" && ! -f "$MIOS_USER_TOML" && ! -f "$MIOS_HOST_TOML" ]]; then
     if [[ -f "${MIOS_CONFIG_DIR}/env.toml" ]]; then
         f="${MIOS_CONFIG_DIR}/env.toml"
         for key in MIOS_USER MIOS_HOSTNAME MIOS_FLATPAKS MIOS_BASE_IMAGE MIOS_LOCAL_TAG; do
@@ -157,7 +226,6 @@ if [[ ! -f "$MIOS_UNIFIED_TOML" ]]; then
         flat=$(grep -vE '^\s*(#|$)' "${MIOS_CONFIG_DIR}/flatpaks.list" 2>/dev/null | paste -sd,)
         [[ -n "$flat" ]] && export "MIOS_FLATPAKS=$flat"
     fi
-    # Legacy bare `env` file -- shell-format KEY=VALUE, source it directly.
     if [[ -f "${MIOS_CONFIG_DIR}/env" ]]; then
         set -a
         # shellcheck disable=SC1091
diff --git a/usr/share/mios/mios.toml b/usr/share/mios/mios.toml
