docs(ssot),fix(sbom): retarget every PACKAGES.md citation at mios.toml

Follow-on cleanup to commit 4f3ca0c, which moved the runtime SSOT to
mios.toml [packages.<section>].pkgs and PACKAGES.md to the docs tree.
The user-facing surface (system prompts, agent tool descriptions, API
example payloads, README, CONTRIBUTING) still pointed at the legacy
SSOT path; this commit lands every remaining citation update.

Touched files:

- tools/lib/generate-sbom.py: parse mios.toml via tomllib instead of
  scraping fenced ```packages-<cat>``` blocks; emit "From mios.toml
  [packages.<cat>].pkgs" provenance lines. MiOS-SBOM.csv regenerated:
  399 rows (was 388), all rows now cite the TOML SSOT.
- usr/lib/mios/tools/{chat-completions-api,responses-api}/packages_md_query.json:
  description now points at mios.toml; section enum updated to reflect
  the actual sub-table names. Tool name retained for tool-call compat
  (rename would propagate through tools.json + dispatcher).
- usr/share/mios/ai/v1/tools.json: matching index entry retargeted.
- etc/mios/system-prompts/{mios-engineer,mios-reviewer,mios-troubleshoot}.md:
  the three operator personas now declare mios.toml as the package SSOT;
  the reviewer's hard-check rule renames "PACKAGES.md SSOT" -> "mios.toml SSOT".
- usr/share/mios/ai/system.md: canonical agent prompt's table row
  pointing at PACKAGES.md retargeted.
- usr/share/mios/api/{chat,chat.local,responses,embeddings}.example.json:
  citation strings in the canonical API payloads retargeted (the
  embeddings example also gets a tighter rewrite).
- README.md, CONTRIBUTING.md, mios.toml comment block: prose pointers
  retargeted; CONTRIBUTING #3 now tells contributors to edit
  [packages.<section>] (or use the configurator HTML), not PACKAGES.md.
- var/lib/mios/evals/mios-knowledge.local-runner.py: default
  citation hint no longer references PACKAGES.md.
- automation/manifest.json + tools/manifest.json: regenerated via
  tools/generate-ai-manifest.py so the AI surface sees the updated
  source bodies.

Why: the user's "deprecate -> consolidate -> remove" arc finishes only
when every consumer of the SSOT name has been retargeted. KB/training
.jsonl and reference docs still carry stale snapshots, but those
regenerate on the next KB/build cycle.

Author: Kabuki94

CONTRIBUTING.md

@@ -2,9 +2,12 @@
 
 ## Project rules
 
-- **Single source of truth: `usr/share/mios/ai/INDEX.md` + `usr/share/mios/PACKAGES.md`.**
-  Every package belongs in `PACKAGES.md`, every architectural rule in
-  `usr/share/mios/ai/INDEX.md`. Other docs cite, never duplicate.
+- **Single source of truth: `usr/share/mios/ai/INDEX.md` + `usr/share/mios/mios.toml`.**
+  Every package belongs in `mios.toml [packages.<section>].pkgs`,
+  every architectural rule in `usr/share/mios/ai/INDEX.md`. Other docs
+  cite, never duplicate. Human-readable package documentation lives at
+  `usr/share/doc/mios/reference/PACKAGES.md` -- it is documentation, not
+  the runtime SSOT.
 - **USR-OVER-ETC, NO-MKDIR-IN-VAR, BOUND-IMAGES, BOOTC-CONTAINER-LINT,
   UNIFIED-AI-REDIRECTS, UNPRIVILEGED-QUADLETS** -- see `usr/share/mios/ai/INDEX.md` §3.
   Violating any of the six is a build/audit fail.
@@ -95,7 +98,11 @@ cleanup.
 
 1. Branch from `main`.
 2. Local validation: `just build` (Containerfile lint runs as final RUN).
-3. If you added or changed packages, edit `usr/share/mios/PACKAGES.md`.
+3. If you added or changed packages, edit `usr/share/mios/mios.toml`
+   under the matching `[packages.<section>]` table (the configurator
+   HTML at `usr/share/mios/configurator/index.html` is the WYSIWYG
+   editor for the same file). Update `usr/share/doc/mios/reference/PACKAGES.md`
+   in the same PR if the prose rationale changes.
 4. If user-facing, bump `VERSION`.
 5. Open a PR against `main`.
 

MiOS-SBOM.csv

@@ -139,9 +139,14 @@ etc.) and the numeric prefix encodes execution order. Add a new step? Drop
 a new `45-myfeature.sh` next to its peers.
 
 If you want to know what makes a package show up in the image, check
-[`usr/share/mios/PACKAGES.md`](usr/share/mios/PACKAGES.md) -- it's the single
-source of truth, parsed at build time. Want to know what kernel arguments
-ship? They're in [`usr/lib/bootc/kargs.d/`](usr/lib/bootc/kargs.d/).
+[`usr/share/mios/mios.toml`](usr/share/mios/mios.toml) under
+`[packages.<section>].pkgs` -- that's the runtime source of truth,
+parsed by `automation/lib/packages.sh` and edited via the configurator
+HTML at `/usr/share/mios/configurator/`. Human-readable companion
+documentation lives at
+[`usr/share/doc/mios/reference/PACKAGES.md`](usr/share/doc/mios/reference/PACKAGES.md).
+Want to know what kernel arguments ship? They're in
+[`usr/lib/bootc/kargs.d/`](usr/lib/bootc/kargs.d/).
 
 ---
 

README.md

@@ -28,9 +28,11 @@ stacks (hadolint, shellcheck SC2038, TOML validation).
 1. The repo root **is** the system root. `usr/`, `etc/`, `home/`, `srv/`,
    `v1/` mirror the deployed image 1:1. **There is no `system_files/`
    directory.** Never reference one.
-2. The single source of truth for packages is `usr/share/mios/PACKAGES.md`.
-   Categories live in fenced ` ```packages-<category>` blocks parsed by
-   `automation/lib/packages.sh:get_packages`. Never invent package names.
+2. The single source of truth for packages is `usr/share/mios/mios.toml`
+   under `[packages.<section>].pkgs`. The TOML chain is resolved by
+   `automation/lib/packages.sh:get_packages`. The companion human-readable
+   reference is `usr/share/doc/mios/reference/PACKAGES.md` (documentation
+   only). Never invent package names.
 3. Build orchestration: Linux uses `Justfile` (`just build | iso | raw |
    qcow2 | vhdx | wsl2 | sbom | rechunk | lint | preflight`). Windows uses
    `mios-build-local.ps1` (5-phase). Numbered phase scripts live at
@@ -65,8 +67,8 @@ stacks (hadolint, shellcheck SC2038, TOML validation).
 - Markdown only where semantically correct (inline code, code fences, lists, tables).
 - Wrap file paths, commands, package names, unit names, and image refs in backticks.
 - Cite the exact MiOS file or upstream doc when stating a fact (e.g. "per
-  `usr/share/mios/ai/INDEX.md` §3", "per `usr/share/mios/PACKAGES.md`",
-  "per bootc kargs docs").
+  `usr/share/mios/ai/INDEX.md` §3", "per `usr/share/mios/mios.toml`
+  `[packages.<section>]`", "per bootc kargs docs").
 - If a question is ambiguous between MiOS and upstream behavior, answer
   for MiOS first, then note the upstream baseline.
 - **Refuse to fabricate.** If unsure, say so and propose the smallest

automation/manifest.json

@@ -9,9 +9,12 @@ established conventions.
 
 ## Hard checks (PR must fail any of these)
 
-1. **PACKAGES.md SSOT** — any package installed by a phase script must
-   appear in a fenced ` ```packages-<category>` block in
-   `usr/share/mios/PACKAGES.md`. CI cross-references this.
+1. **mios.toml SSOT** — any package installed by a phase script must
+   appear in `[packages.<section>].pkgs` in `usr/share/mios/mios.toml`,
+   resolved by `automation/lib/packages.sh:get_packages`. CI
+   cross-references this. The companion `usr/share/doc/mios/reference/PACKAGES.md`
+   is documentation only; the legacy fenced-block fallback was removed
+   in v0.2.4.
 2. **Containerfile invariants** — final RUN remains `bootc container lint`;
    no `--squash-all`; kernel rule (`kernel`/`kernel-core` excluded) intact;
    `dnf install_weak_deps=False` (underscore form).

etc/mios/system-prompts/mios-engineer.md

@@ -25,7 +25,7 @@ When given a symptom, walk this checklist before proposing a fix:
 3. **Find the source-of-truth file** in the repo overlay (`usr/`, `etc/`,
    `home/`, `srv/`, `v1/`). Cite it in the response.
 4. **Propose a fix** that:
-   - prefers image-layer changes (PACKAGES.md, kargs.d, `system_files/`-style overlay paths)
+   - prefers image-layer changes (`mios.toml [packages.<section>]`, kargs.d, `system_files/`-style overlay paths)
    - over runtime mutations
    - reverts cleanly via `bootc rollback` if it's image-layer
    - or via override files in `/etc/` if it's admin-layer

etc/mios/system-prompts/mios-reviewer.md

@@ -1,10 +1,13 @@
 #!/usr/bin/env python3
-# tools/lib/generate-sbom.py -- emit MiOS-SBOM.csv from PACKAGES.md +
-# Quadlet Image= refs + base image refs + .env.mios Flatpak defaults.
+# tools/lib/generate-sbom.py -- emit MiOS-SBOM.csv from mios.toml
+# [packages.<section>].pkgs + Quadlet Image= refs + base image refs +
+# .env.mios Flatpak defaults. As of v0.2.4 (2026-05-05) PACKAGES.md is
+# documentation only; mios.toml is the runtime SSOT.
 
 import re
 import csv
 import sys
+import tomllib
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parents[2]
@@ -109,26 +112,28 @@
 def main(out_path: Path):
     rows = []
 
-    # 1. PACKAGES.md
-    pmd = (ROOT / "usr/share/mios/PACKAGES.md").read_text(encoding="utf-8")
-    section_re = re.compile(r"^```packages-([a-z0-9-]+)\s*\n(.*?)^```\s*$", re.MULTILINE | re.DOTALL)
-    for m in section_re.finditer(pmd):
-        cat = m.group(1)
-        body = m.group(2)
+    # 1. mios.toml [packages.<section>].pkgs (runtime SSOT)
+    toml_path = ROOT / "usr/share/mios/mios.toml"
+    with toml_path.open("rb") as fh:
+        toml = tomllib.load(fh)
+    pkg_tables = toml.get("packages", {}) or {}
+    for cat, table in sorted(pkg_tables.items()):
+        if not isinstance(table, dict):
+            continue
+        pkgs = table.get("pkgs", []) or []
+        if not pkgs:
+            continue
         classification, purpose = CAT_META.get(cat, (f"rpm-{cat}", "(uncategorized)"))
-        for ln in body.splitlines():
-            ln = ln.strip()
-            if not ln or ln.startswith("#"):
-                continue
-            ln = ln.split("#", 1)[0].strip()
-            if not ln:
+        for pkg in pkgs:
+            pkg = (pkg or "").strip()
+            if not pkg:
                 continue
             rows.append({
                 "section":        f"packages-{cat}",
-                "package":        ln,
+                "package":        pkg,
                 "classification": classification,
                 "purpose":        purpose,
-                "notes":          f"From usr/share/mios/PACKAGES.md packages-{cat} block",
+                "notes":          f"From usr/share/mios/mios.toml [packages.{cat}].pkgs",
             })
 
     # 2. From-source

etc/mios/system-prompts/mios-troubleshoot.md

@@ -2,7 +2,7 @@
   "type": "function",
   "function": {
     "name": "packages_md_query",
-    "description": "Query the MiOS PACKAGES.md SSOT (at usr/share/mios/PACKAGES.md). Returns whether a package is included, the fenced-block category that installs it, and the install helper that consumes the block. Categories live in fenced ```packages-<category>``` blocks parsed by automation/lib/packages.sh:get_packages.",
+    "description": "Query the MiOS package SSOT (mios.toml [packages.<section>].pkgs at usr/share/mios/mios.toml). Returns whether a package is included, the section table that installs it, and the install helper that consumes the table. As of v0.2.4 the legacy PACKAGES.md fenced-block fallback is removed; mios.toml is the only runtime source. The companion human-readable doc is usr/share/doc/mios/reference/PACKAGES.md.",
     "strict": true,
     "parameters": {
       "type": "object",
@@ -19,19 +19,28 @@
           ],
           "enum": [
             "base",
+            "ai",
+            "boot",
+            "ceph",
+            "cockpit",
+            "containers",
             "critical",
-            "self-build",
-            "desktop",
-            "nvidia",
+            "gnome",
+            "gpu-nvidia",
+            "gpu-mesa",
             "k3s",
-            "ceph",
-            "ai",
-            "gpu",
+            "kernel",
+            "security",
+            "self-build",
+            "storage",
+            "uki",
+            "updater",
+            "utils",
             "virt",
             "all",
             null
           ],
-          "description": "Optional category filter. 'all' searches every fenced block. Null defaults to 'all'."
+          "description": "Optional [packages.<section>] filter. 'all' searches every section table. Null defaults to 'all'."
         }
       },
       "required": [