docs(arch,eng): compact upstream research; expand FHS/bootc layout; fix AI refs

- ARCHITECTURE.md: add uCore HCI base image section (CoreOS foundation,
  LTS 6.12 kernel, pre-signed NVIDIA akmods, libvirt/KVM, ZFS, SELinux);
  expand FHS table with bootc disposition column + /run and /home rows;
  add bootc 3-way merge explanation for /etc; fix AI surface table to
  reference MIOS_AI_ENDPOINT; document OpenAI v1 API endpoints, streaming
  SSE, tool calling; fix bootc and uCore upstream URLs in references.
- ENGINEERING.md: add upstream bootc constraints section documenting what
  bootc container lint enforces and the kargs.d flat-array-only rule.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mios-dev

ARCHITECTURE.md

@@ -14,16 +14,43 @@
    USBGuard, CrowdSec sovereign-mode IPS, kernel-lockdown integrity. See
    `SECURITY.md`.
 
+## Base image — uCore HCI
+
+MiOS builds `FROM ghcr.io/ublue-os/ucore-hci:stable-nvidia` (`MIOS_BASE_IMAGE`).
+uCore HCI is a Universal Blue derivative of Fedora CoreOS targeting
+hyperconverged infrastructure:
+
+| Layer | What it provides |
+|---|---|
+| Fedora CoreOS foundation | Immutable ostree rootfs, composefs `/usr`, SELinux enforcing, podman, ZFS kernel modules |
+| uCore additions | cockpit, firewalld, tailscale, mergerfs, samba, NFS |
+| HCI additions | libvirt/KVM, QEMU, VFIO-PCI tooling, virtiofs |
+| NVIDIA variant (`stable-nvidia`) | Proprietary driver akmods pre-built and MOK-signed; NVIDIA Container Toolkit |
+| Stable stream kernel | LTS Linux 6.12 — server-grade stability, consistent ABI across updates |
+
+MiOS adds: GNOME 50 desktop, Looking Glass B7, KVM passthrough, k3s, Ceph,
+full AI surface, and defense-in-depth hardening on top.
+
+Upstream: <https://github.com/ublue-os/ucore>
+
 ## Filesystem layout (FHS 3.0 + bootc)
 
 Spec: <https://refspecs.linuxfoundation.org/FHS_3.0/>.
 
-| Path | Type | Source-of-truth in repo |
-|---|---|---|
-| `/usr` | Immutable image content | `usr/` (overlaid by `automation/08-system-files-overlay.sh`) |
-| `/etc` | Persistent admin-override surface; build-time writes are upstream-contract only | `etc/` |
-| `/var` | Persistent state; declared via `tmpfiles.d` | `usr/lib/tmpfiles.d/mios*.conf` |
-| `/srv` | Sidecar service data (models, databases) | `srv/`, `usr/lib/tmpfiles.d/mios.conf` |
+bootc disposition reflects FHS 3.0's intent: `/usr` is explicitly
+"shareable, read-only" in the spec — the composefs/ostree model enforces this
+at the kernel level. `/etc` is the host-specific config surface; bootc applies
+a 3-way merge (image default + previous state + admin edits) on upgrade so
+local changes survive. `/var` is never touched by an upgrade.
+
+| Path | FHS character | bootc disposition | Source-of-truth in repo |
+|---|---|---|---|
+| `/usr` | Read-only, shareable | Immutable composefs mount; change = new OCI image | `usr/` overlaid by `automation/08-system-files-overlay.sh` |
+| `/etc` | Host-specific config | 3-way merge overlay; admin edits survive upgrades | `etc/` |
+| `/var` | Mutable, persistent | Fully writable; never replaced on upgrade | `usr/lib/tmpfiles.d/mios*.conf` (LAW 2) |
+| `/srv` | Data served by the system | Persistent; AI model weights, Ceph data | `usr/lib/tmpfiles.d/mios.conf` |
+| `/run` | Ephemeral runtime (FHS 3.0) | tmpfs; cleared at boot; never in image layers | — |
+| `/home` | User home directories | Persistent via `/var/home/<user>` + symlink | `usr/lib/sysusers.d/` |
 
 Build-time writes to `/var/` are forbidden (LAW 2). The overlay step at
 `automation/08-system-files-overlay.sh:49-67` writes home dotfiles to
@@ -43,17 +70,23 @@ in-image (`automation/53-bake-lookingglass-client.sh`).
 
 ## AI surface
 
+All agents and tooling target `MIOS_AI_ENDPOINT` (`http://localhost:8080/v1`).
+The endpoint implements the OpenAI v1 REST protocol — core surfaces:
+`GET /v1/models`, `POST /v1/chat/completions` (streaming SSE supported),
+`POST /v1/embeddings`. Auth: `Authorization: Bearer $MIOS_AI_KEY` (empty key
+accepted by the local stack). Tool calling (`tools` array,
+`finish_reason: tool_calls`) is supported for capable models.
+
 | Service | Protocol | Path |
 |---|---|---|
-| Inference | OpenAI-compatible REST | `http://localhost:8080/v1` (LocalAI Quadlet `etc/containers/systemd/mios-ai.container`) |
+| Inference | OpenAI v1 REST | `MIOS_AI_ENDPOINT` (`http://localhost:8080/v1`) — Quadlet `etc/containers/systemd/mios-ai.container` |
 | Discovery | MCP | `usr/share/mios/ai/v1/mcp.json` |
 | Metadata | JSON | `usr/share/mios/ai/v1/models.json` |
 | System prompt | markdown | `usr/share/mios/ai/system.md` (canonical), `etc/mios/ai/system-prompt.md` (host override) |
 
 References:
-- bootc: <https://github.com/containers/bootc>
+- bootc: <https://github.com/bootc-dev/bootc>
 - bootc-image-builder: <https://github.com/osbuild/bootc-image-builder>
-- Universal Blue (uCore base): <https://github.com/ublue-os/main>
+- Universal Blue uCore HCI: <https://github.com/ublue-os/ucore>
 - rechunk: <https://github.com/hhd-dev/rechunk>
 - cosign: <https://github.com/sigstore/cosign>
-- LocalAI: <https://github.com/mudler/LocalAI>

ENGINEERING.md

@@ -95,6 +95,21 @@ fcontexts are declared via `semanage` calls in `automation/37-selinux.sh`.
   `/var/lib/mios/memory/journal/` via `usr/lib/tmpfiles.d/mios.conf`.
 - Declarative state: `tmpfiles.d` and `sysusers.d` only.
 
+## Upstream base image constraints (bootc)
+
+`bootc container lint` (LAW 4) enforces at build time:
+- Kernel present and detectable at `/usr/lib/modules/<kver>/vmlinuz`
+- No files written under `/var` or `/run` in image layers — these are
+  runtime-mutable and never part of the composefs rootfs
+- `/usr` structurally valid (no dangling symlinks, no unexpected setuid files)
+- OCI config has `architecture` and `os` fields set
+- `systemd` must be PID 1 (init at `/sbin/init`)
+
+kargs.d constraint (also enforced by lint): flat `kargs = [...]` TOML array
+only. No `[kargs]` section header, no `delete` sub-key. Files processed in
+lexicographic order; earlier entries cannot be removed by later files in the
+same image — use runtime `bootc kargs --delete` for removal.
+
 ## Toolchain
 
 | Tool | Use |