|
1 | | -# MiOS SYSTEM CONTEXT — API Native (Day 0) |
| 1 | +# MiOS v0.2.2 — Flattened System Context |
2 | 2 |
|
3 | | -This document provides a flattened, high-density map of the MiOS environment for autonomous agent ingestion. |
| 3 | +MiOS is an immutable, bootc-native Fedora workstation OS. Repo root `mios.git` IS the system root `/`. |
4 | 4 |
|
5 | 5 | --- |
6 | 6 |
|
7 | | -## 1. ARCHITECTURAL SSOT (INDEX.md) |
8 | | -MiOS is an immutable, AI-native workstation. |
| 7 | +## Architectural Laws (INDEX.md, non-negotiable) |
9 | 8 |
|
10 | | -### ⚖️ Immutable Appliance Laws |
11 | | -1. **USR-OVER-ETC**: Static config in `/usr/lib/`. `/etc` for admin overrides. |
12 | | -2. **NO-MKDIR-IN-VAR**: Persistence via `tmpfiles.d`. No build-time `/var` overlays. |
13 | | -3. **UNPRIVILEGED-QUADLETS**: sidecars execute as unprivileged service accounts. |
14 | | -4. **BOOTC-NATIVE**: Lifecycle managed via `bootc` and signed OCI images. |
| 9 | +1. **USR-OVER-ETC** — Static config in `/usr/lib/<component>.d/`. `/etc/` for admin overrides only. Exception: `/etc/mios/install.env` (first-boot). |
| 10 | +2. **NO-MKDIR-IN-VAR** — All `/var/` paths declared via `usr/lib/tmpfiles.d/*.conf`. No `mkdir` in build scripts. |
| 11 | +3. **BOUND-IMAGES** — Every Quadlet sidecar image symlinked in `/usr/lib/bootc/bound-images.d/`. |
| 12 | +4. **BOOTC-CONTAINER-LINT** — `RUN bootc container lint` is the final Containerfile instruction. Always. |
| 13 | +5. **UNIFIED-AI-REDIRECTS** — `MIOS_AI_ENDPOINT/MODEL/KEY` target `http://localhost:8080/v1`. Zero vendor URLs in committed files. |
| 14 | +6. **UNPRIVILEGED-QUADLETS** — Every Quadlet: `User=`, `Group=`, `Delegate=yes`. Exception: `mios-k3s.container` and `mios-ceph.container`. |
15 | 15 |
|
16 | | -### 🤖 AI Agent Surface Contract |
17 | | -- **Endpoint**: `http://localhost:8080/v1` (OpenAI-API compatible). |
18 | | -- **Interface Protocols**: REST, MCP (Model Context Protocol). |
19 | | -- **Discovery Hub**: `/usr/share/mios/ai/`. |
| 16 | +## AI Agent Surface |
20 | 17 |
|
21 | | ---- |
| 18 | +- **Endpoint**: `http://localhost:8080/v1` (LocalAI v2.20.0, OpenAI-compatible) |
| 19 | +- **Inference model**: `qwen2.5-coder:7b` (`MIOS_AI_MODEL`) |
| 20 | +- **Embedding model**: `nomic-embed-text` (`MIOS_AI_EMBED_MODEL`) |
| 21 | +- **MCP registry**: `/usr/share/mios/ai/mcp.json` |
| 22 | +- **System prompt resolution**: `$MIOS_AI_SYSTEM_PROMPT` > `~/.config/mios/system-prompt.md` > `/etc/mios/ai/system-prompt.md` > `/usr/share/mios/ai/system.md` |
22 | 23 |
|
23 | | -## 2. ENVIRONMENT MAP (Indexed Verbs) |
| 24 | +## Directory Hierarchy |
24 | 25 |
|
25 | | -| Variable | Verb | Intent | |
| 26 | +| Path | Persistence | Purpose | |
26 | 27 | |---|---|---| |
27 | | -| `MIOS_AI_KEY` | `SET_KEY` | Set local inference API key. | |
28 | | -| `MIOS_AI_MODEL` | `SET_MODEL` | Set target LLM for operations. | |
29 | | -| `MIOS_BASE_IMAGE` | `GET_BASE` | Get root image reference. | |
| 28 | +| `/usr/bin/mios` | Immutable | OpenAI client CLI | |
| 29 | +| `/usr/lib/` | Immutable | systemd units, kargs.d, tmpfiles.d, sysctl.d, bootc/ | |
| 30 | +| `/usr/share/mios/` | Immutable | PACKAGES.md, env.defaults, profile.toml, ai/ | |
| 31 | +| `/usr/share/mios/ai/` | Image (bootstrap) | system.md, models.json, mcp.json | |
| 32 | +| `/etc/mios/` | Persistent | profile.toml, install.env, ai/system-prompt.md | |
| 33 | +| `/var/lib/mios/ai/` | Persistent | memory/, scratch/, journal.md | |
| 34 | +| `/srv/ai/models/` | Persistent | GGUF/safetensors weights | |
| 35 | +| `/etc/containers/systemd/` | Immutable | Quadlet sidecar units + mios.network | |
30 | 36 |
|
31 | | ---- |
| 37 | +## Build Pipeline (48 numbered scripts) |
32 | 38 |
|
33 | | -## 3. DIRECTORY HIERARCHY (Rootfs-Native) |
| 39 | +`Containerfile` -> `08-system-files-overlay.sh` (FHS copy) -> `build.sh` -> all numbered scripts -> `bootc container lint`. |
34 | 40 |
|
35 | | -| Path | Persistence | Purpose | |
36 | | -| :--- | :--- | :--- | |
37 | | -| `/usr/bin/` | Immutable | Core system binaries and MiOS CLI. | |
38 | | -| `/usr/lib/` | Immutable | Static configuration and systemd units. | |
39 | | -| `/usr/share/mios/ai/v1/` | Immutable | Consolidated AI specifications and API discovery. | |
40 | | -| `/etc/` | Persistent | Host-specific administrative overrides. | |
41 | | -| `/var/lib/mios/` | Persistent | Local application state and AI models. | |
42 | | -| `/srv/ai/` | Persistent | Large model weights and vector stores. | |
| 41 | +| Phase range | Purpose | |
| 42 | +|---|---| |
| 43 | +| 01-05 | Repos, kernel, external repo enables | |
| 44 | +| 08 | FHS overlay copy + bound-images symlinks | |
| 45 | +| 10-13 | GNOME 50, hardware/GPU, KVM/Cockpit, Ceph/K3s | |
| 46 | +| 18-26 | Boot fixes, K3s SELinux, fapolicyd, services, FreeIPA, UKI, firewall, GRD | |
| 47 | +| 30-36 | Locale/theme, user creation, hostname, firewall, GPU detect/passthrough/PV | |
| 48 | +| 37-40 | aichat, Flatpak, SELinux modules, VM gating, composefs-verity | |
| 49 | +| 42-47 | cosign, uupd, podman-machine compat, NVIDIA CDI, greenboot, hardening | |
| 50 | +| 49-50 | Finalize, log-copy service enable | |
| 51 | +| 52-53 | KVMFR akmod (MOK-signed), Looking Glass B7 | |
| 52 | +| 90-99 | SBOM, boot config, cleanup, postcheck (build gate) | |
43 | 53 |
|
44 | | ---- |
| 54 | +## Env Cascade (highest wins) |
45 | 55 |
|
46 | | -## 4. AGENT SPECIFICATION (system.md) |
47 | | -- **Protocol**: OpenAI-compatible API (`/v1`). |
48 | | -- **Directives**: evidence-based, path-citing, FOSS-first. |
49 | | -- **Constraints**: No proprietary cloud APIs, no immutability violations. |
| 56 | +`~/.config/mios/env` > `/etc/mios/install.env` > `/etc/mios/env.d/*.env` > `/usr/share/mios/env.defaults` |
50 | 57 |
|
51 | | ---- |
| 58 | +Key vars: `MIOS_AI_ENDPOINT`, `MIOS_AI_MODEL`, `MIOS_AI_EMBED_MODEL`, `MIOS_BASE_IMAGE`, `MIOS_VERSION` |
52 | 59 |
|
53 | | -## 5. SYSTEM TOOLCHAIN |
54 | | -- `bootc`: `UPGRADE_CORE` — Atomic system updates. |
55 | | -- `podman`: `RUN_SIDECAR` — Orchestrate unprivileged sidecars. |
56 | | -- `mios-status`: `GET_STATE` — JSON-native system telemetry. |
| 60 | +## System Toolchain |
57 | 61 |
|
58 | | ---- |
59 | | -*Copyright (c) 2026 MiOS. Pure FOSS. Day 0 Ready.* |
| 62 | +- `bootc upgrade && systemctl reboot` — atomic update |
| 63 | +- `bootc switch <ref>` — change image ref |
| 64 | +- `bootc rollback` — undo last upgrade |
| 65 | +- `just build` — build OCI image locally |
| 66 | +- `mios "<prompt>"` — query local AI |
| 67 | + |
| 68 | +## Sanitization (all persisted AI artifacts) |
| 69 | + |
| 70 | +No vendor/corporate entity names in prose. No chat metadata. No foreign sandbox paths. All AI endpoints target `http://localhost:8080/v1`. Upstream package names, FHS paths, and protocol names (`/v1/chat/completions`) survive unchanged. |
0 commit comments