RESTRUCTURE: three-layer profile, multi-user skel, AI surface trim, CI fix

Three-layer profile + env model. Each layer overlays the one above it
field-by-field; user-set fields supersede defaults; empty strings do not
override non-empty layers below.

Profile layers (highest precedence first):
  ~/.config/mios/profile.toml           per-user (skel-seeded)
  /etc/mios/profile.toml                host (mios-bootstrap)
  /usr/share/mios/profile.toml          vendor defaults (THIS REPO)  ← NEW

Env layers:
  ~/.config/mios/env, /etc/mios/install.env, /etc/mios/env.d/*.env,
  /usr/share/mios/env.defaults  ← NEW
  ~/.env.mios is kept as a deprecated legacy fallback.

New mios.git files:
- usr/share/mios/profile.toml — vendor defaults TOML, full field shape
  (identity, locale, auth, network, ai, desktop, image, bootstrap,
  quadlets.enable). Immutable per USR-OVER-ETC; bootstrap overlays.
- usr/share/mios/env.defaults — vendor env defaults.

AI surface restructure (minimum OpenAI-API patterns; retain code):
- system.md (29 KB canonical agent prompt) moved from repo root to
  usr/share/mios/ai/system.md (FHS-correct vendor location). Repo-root
  /system.md is now a symlink to that path for off-host fallback;
  .gitignore re-whitelists the symlink.
- Header sanitized: dropped "Claude Code, Gemini Code, Codex, Cursor,
  Aider, Continue" CLI list (vendor brand prose). Replaced with
  "AGENTS.md-aware CLI agents". Deployment-paths table extended to
  include /system.md symlink and ~/.config/mios/system-prompt.md
  per-user override.
- Dropped duplicates/stale: usr/share/mios/ai/v1/{system.md,context.json,
  knowledge.md}. context.json referenced an obsolete /v1/system endpoint;
  v1/system.md duplicated the canonical; v1/knowledge.md duplicated
  INDEX.md/ARCHITECTURE.md/ENGINEERING.md.
- Kept v1/models.json and v1/mcp.json (the actual OpenAI-API surface).

CI build fix:
- Containerfile: `find /var -mindepth 1 -maxdepth 1 ! -name tmp -exec
  rm -rf` now also excludes `cache`. /var/cache/{libdnf5,dnf} are
  buildkit cache mounts (--mount=type=cache) and are still bound during
  the RUN, so rm returned EBUSY and failed the build. Buildkit doesn't
  bake cache mounts into the layer regardless.

Sanitization (vendor brand + emoji decoration + marketing prose):
- automation/ai-bootstrap.sh: replace 🚀/📜/📄/📖/🧠/🌱/✅ with
  bracketed log-level prefixes; add file header.
- usr/share/mios/PACKAGES.md: drop 🌐 emoji header and 📚 ecosystem
  block; consolidate ecosystem links to a clean reference list.
- .github/ai-instructions.md: drop 🤝/🤖/🛠 emoji headers;
  rewrite to vendor-agnostic, FHS-cited prose.
- tools/README.md: drop the [NET] MiOS Artifact / Proprietor preamble +
  json:knowledge sidebar + ecosystem footer. Reference LICENSES.md /
  CONTRIBUTING.md instead.
- tools/log-to-bootstrap.sh, tools/mios-overlay.sh: replace ❌/✅/⚠️
  with [ OK ] / WARN: / ERROR: bracket prefixes.

Doc updates:
- CLAUDE.md: dual-repo split table now lists exact deployed-system
  paths and their owner repo (vendor defaults vs. user overrides vs.
  per-user templates).
- INDEX.md §4 (renamed from "Environment contract" to
  "Profile + environment resolution"): documents the three-layer
  profile and five-layer env resolution explicitly.

Final brand-mention sweep: clean across both repos. The two surviving
hits in usr/share/mios/ai/system.md (lines 297, 326) are inside the
forbidden-token rule definition itself — meta-prose, expected per §6.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: mios-dev

.github/ai-instructions.md

@@ -1,20 +1,31 @@
 # MiOS AI Integration — GitHub Instructions
 
-Welcome to the **MiOS** repository. This project is a bootc-based, AI-native immutable workstation.
+MiOS is a bootc-based, AI-native immutable workstation. AI agents
+contributing to this repo must follow the rules in `INDEX.md` and the
+canonical agent prompt at `usr/share/mios/ai/system.md`.
 
-## 🤝 Contribution Rules for AI Agents
-1. **Architectural Integrity:** All changes must comply with the "Immutable Appliance Laws" in `INDEX.md`.
-2. **OpenAI Native:** Maintain compatibility with the local OpenAI-API surface at `http://localhost:8080/v1`.
-3. **FHS Compliance:** Ensure all filesystem overlays follow Linux FHS 3.0.
-4. **Documentation:** Every new feature or blueprint must include a `json:knowledge` block in its Markdown header.
+## Contribution rules for AI agents
 
-## 🤖 Integration Points
-- **System Prompt:** `system-prompt.md`
-- **AI Agent Hub:** `INDEX.md`
-- **Context Discovery:** `llms.txt`
-- **RAG Snapshot:** `artifacts/repo-rag-snapshot.json.gz`
+1. **Architectural laws:** changes must comply with the six laws listed
+   in `INDEX.md` §3.
+2. **OpenAI v1 compatibility:** preserve the local OpenAI-compatible
+   surface at `http://localhost:8080/v1`.
+3. **FHS 3.0:** filesystem overlays follow the Filesystem Hierarchy
+   Standard 3.0 (<https://refspecs.linuxfoundation.org/FHS_3.0/>).
+4. **Sanitization:** persisted artifacts comply with
+   `usr/share/mios/ai/system.md` §6 — no vendor brand prose, no chat
+   metadata, no foreign sandbox path traces.
 
-## 🛠 Quick Actions
-- **Validate Image:** `just build`
-- **Sync Knowledge:** `./automation/ai-bootstrap.sh`
-- **Check Linting:** `bootc container lint`
+## Integration points
+
+- **Canonical system prompt:** `usr/share/mios/ai/system.md`
+  (host override: `/etc/mios/ai/system-prompt.md`,
+  per-user: `~/.config/mios/system-prompt.md`).
+- **Architectural index:** `INDEX.md`.
+- **AI ingestion index:** `llms.txt`, `llms-full.txt`.
+
+## Quick actions
+
+- Validate image: `just build` (Containerfile final RUN is `bootc container lint`).
+- Refresh AI manifests: `./automation/ai-bootstrap.sh`.
+- Re-run lint on built image: `just lint`.

.gitignore

@@ -37,6 +37,7 @@
 !/README.md
 !/SECURITY.md
 !/SELF-BUILD.md
+!/system.md
 !/VERSION
 !/llms-full.txt
 !/llms.txt

CLAUDE.md

@@ -124,11 +124,24 @@ so bootc pre-pulls it offline.
 This repo (`mios.git`) and `mios-bootstrap.git` resolve to the same physical
 root on the dev host but each gitignore whitelists a *different subset*. The
 `.gitignore` here is a **whitelist inverter** — `/*` ignores everything,
-then `!/path` re-includes the system-overlay subset. When committing, verify
-each path matches a negation; an untracked file outside the whitelist is
-correct gitignore behavior, not "a file to add". User/installer files
-(`/etc/mios/manifest.json`, user-account skeleton, knowledge graphs) belong
-in `mios-bootstrap.git`, not here.
+then `!/path` re-includes the system-overlay subset.
+
+| Path on deployed system | Owner repo | Purpose |
+|---|---|---|
+| `/usr/share/mios/profile.toml` | `mios.git` | vendor profile defaults (immutable) |
+| `/usr/share/mios/env.defaults` | `mios.git` | vendor env defaults |
+| `/usr/share/mios/ai/system.md` | `mios.git` | canonical agent prompt |
+| `/etc/mios/profile.toml` | `mios-bootstrap.git` | host/admin profile overrides |
+| `/etc/mios/install.env` | `mios-bootstrap.git` | runtime identity (written at install) |
+| `/etc/mios/ai/system-prompt.md` | `mios-bootstrap.git` | host AI prompt override |
+| `/etc/skel/.config/mios/profile.toml` | `mios-bootstrap.git` | per-user TOML template |
+| `/etc/skel/.config/mios/system-prompt.md` | `mios-bootstrap.git` | per-user AI prompt template |
+
+When committing to `mios.git`, verify each path matches a whitelist
+negation; an untracked file outside the whitelist is correct gitignore
+behavior, not "a file to add". User-installer files (`/etc/mios/*`,
+`/etc/skel/.config/mios/*`, knowledge graphs) belong in
+`mios-bootstrap.git`, not here.
 
 ## Architectural laws (from INDEX.md / .cursorrules — non-negotiable)
 

Containerfile

@@ -49,7 +49,10 @@ RUN --mount=type=bind,from=ctx,source=/ctx,target=/ctx,ro \
     CTX=/tmp/build /tmp/build/automation/build.sh; \
     dnf clean all; \
     rm -rf /tmp/build; \
-    find /var -mindepth 1 -maxdepth 1 ! -name tmp -exec rm -rf {} +; \
+    # /var/cache is bind-mounted by buildkit (--mount=type=cache above) for
+    # the duration of this RUN, so trying to rm it returns EBUSY. Skip it;
+    # buildkit doesn't bake cache mounts into the layer regardless.
+    find /var -mindepth 1 -maxdepth 1 ! -name tmp ! -name cache -exec rm -rf {} +; \
     find /run -mindepth 1 -maxdepth 1 ! -name "secrets" -exec rm -rf {} + 2>/dev/null || true
 
 RUN bootc completion bash > /etc/bash_completion.d/bootc

INDEX.md

@@ -34,13 +34,33 @@ Spec: <https://platform.openai.com/docs/api-reference>.
 | 5 | **UNIFIED-AI-REDIRECTS** — `MIOS_AI_KEY`, `MIOS_AI_MODEL`, `MIOS_AI_ENDPOINT` → `http://localhost:8080/v1`. No vendor URLs. | `usr/bin/mios`, `etc/mios/ai/` |
 | 6 | **UNPRIVILEGED-QUADLETS** — every Quadlet declares `User=`, `Group=`, `Delegate=yes`. Documented exceptions: `mios-ceph` and `mios-k3s` declare `User=root`/`Group=root` because Ceph/K3s require uid 0 (see file headers). | `etc/containers/systemd/`, `usr/share/containers/systemd/` |
 
-## 4. Environment contract
+## 4. Profile + environment resolution
+
+Both the user profile (TOML) and runtime environment (env-style) follow a
+three-layer overlay. Higher layers supersede lower layers field-by-field.
+
+**Profile layers** (read by `mios-bootstrap/install.sh:load_profile_defaults`
+and at runtime by `mios` CLI clients):
+
+1. `~/.config/mios/profile.toml` — per-user override (highest precedence;
+   seeded into every uid≥1000 home from `/etc/skel/.config/mios/profile.toml`)
+2. `/etc/mios/profile.toml` — host/admin override (shipped by `mios-bootstrap`)
+3. `/usr/share/mios/profile.toml` — vendor defaults (shipped by `mios.git`,
+   immutable, USR-OVER-ETC)
+
+**Environment layers** (resolved by `/etc/profile.d/mios-env.sh` at login):
+
+1. `~/.config/mios/env`
+2. `/etc/mios/install.env` (written by bootstrap install.sh)
+3. `/etc/mios/env.d/*.env` (admin/distro drop-ins)
+4. `/usr/share/mios/env.defaults` (vendor defaults)
+5. `~/.env.mios` (legacy, deprecated; kept for backwards compatibility)
+
+**Build-time variables** read by `Justfile`:
 
 | Variable | Scope | Purpose |
 |---|---|---|
-| `MIOS_AI_KEY` | AI | Local inference key (default empty for unauthenticated localhost). |
-| `MIOS_AI_MODEL` | AI | Target model id resolved via `usr/share/mios/ai/v1/models.json`. |
-| `MIOS_AI_ENDPOINT` | AI | API base URL. Default `http://localhost:8080/v1`. |
+| `MIOS_AI_KEY` / `MIOS_AI_MODEL` / `MIOS_AI_ENDPOINT` | AI | Resolution per LAW 5; defaults in `usr/share/mios/env.defaults`. |
 | `MIOS_BASE_IMAGE` | build | OCI base image (default `ghcr.io/ublue-os/ucore-hci:stable-nvidia`, `Justfile:45`). |
 | `MIOS_LOCAL_TAG` | build | Local image tag (default `localhost/mios:latest`, `Justfile:13`). |
 | `MIOS_USER` / `MIOS_HOSTNAME` | build | Default account/hostname baked into the image (`Containerfile:26-27`). |

automation/ai-bootstrap.sh

@@ -1,75 +1,71 @@
 #!/bin/bash
-# MiOS Omni-Agent Bootstrap Script
-# Synchronizes manifests and initializes sub-project environments.
+# MiOS AI/manifest bootstrap. Regenerates directory manifests, syncs the Wiki,
+# rebuilds the unified knowledge base (RAG snapshot), refreshes user-space
+# environment configs, and seeds shared agent context. Idempotent.
 
 set -euo pipefail
 
-echo "🚀 Initializing MiOS Agent Workspace..."
+echo "[ai-bootstrap] Initializing MiOS agent workspace..."
 
-# 0. Load Unified Environment
+# 0. Load unified environment (legacy .env.mios; deprecated — prefer
+# /etc/mios/profile.toml for new installs).
 if [[ -f ".env.mios" ]]; then
-    echo "📜 Loading unified environment from .env.mios..."
-    # Export all variables defined in .env.mios
+    echo "[ai-bootstrap] Loading legacy environment from .env.mios..."
     set -a
+    # shellcheck disable=SC1091
     source .env.mios
     set +a
 fi
 
-# 1. Generate Manifests
+# 1. Generate manifests.
 if [[ -f "tools/generate-ai-manifest.py" ]]; then
-    echo "📄 Generating directory manifests..."
+    echo "[ai-bootstrap] Generating directory manifests..."
     python3 tools/generate-ai-manifest.py
 else
-    echo "⚠️ Warning: tools/generate-ai-manifest.py not found."
+    echo "[ai-bootstrap] WARN: tools/generate-ai-manifest.py not found"
 fi
 
-# 2. Sync Wiki Documentation
+# 2. Sync Wiki documentation.
 if [[ -f "tools/sync-wiki.py" ]]; then
-    echo "📖 Syncing Wiki..."
+    echo "[ai-bootstrap] Syncing Wiki..."
     python3 tools/sync-wiki.py
 else
-    echo "⚠️ Warning: tools/sync-wiki.py not found."
+    echo "[ai-bootstrap] WARN: tools/sync-wiki.py not found"
 fi
 
-# 3. Generate Unified Knowledge Base (RAG Snapshot)
+# 3. Generate unified knowledge base (RAG snapshot).
 if [[ -f "tools/generate-unified-knowledge.py" ]]; then
-    echo "🧠 Generating Unified Knowledge Base (RAG Snapshot)..."
-    if [[ -f "tools/journal-sync.py" ]]; then
-        python3 tools/journal-sync.py
-    fi
+    echo "[ai-bootstrap] Generating unified knowledge base (RAG snapshot)..."
+    [[ -f "tools/journal-sync.py" ]] && python3 tools/journal-sync.py
     python3 tools/generate-unified-knowledge.py
 else
-    echo "⚠️ Warning: tools/generate-unified-knowledge.py not found."
+    echo "[ai-bootstrap] WARN: tools/generate-unified-knowledge.py not found"
 fi
 
-# 4. Initialize agents/research
+# 4. Initialize agents/research scratchpad if present.
 if [[ -d "agents/research" ]]; then
-    echo "🧪 Initializing agents/research (Agent Starter Pack)..."
-    # Placeholder for future agent initialization logic
-    # (cd agents/research && make install)
+    echo "[ai-bootstrap] Initializing agents/research scratchpad..."
 else
-    echo "⚠️ Warning: agents/research directory not found."
+    echo "[ai-bootstrap] WARN: agents/research directory not found"
 fi
 
-# 3. Persistence: Refresh environment configs and dotfiles
-echo "💾 Persisting environment state..."
+# 5. Refresh environment configs and dotfiles.
+echo "[ai-bootstrap] Persisting environment state..."
 if [[ -f "tools/refresh-env.py" ]]; then
     python3 tools/refresh-env.py
 else
-    echo "⚠️ Warning: tools/refresh-env.py not found."
+    echo "[ai-bootstrap] WARN: tools/refresh-env.py not found"
 fi
 
-echo "✅ Workspace initialization complete."
+echo "[ai-bootstrap] Workspace initialization complete."
 
-# 6. Seed Artifacts for Agents
-echo "🌱 Seeding latest MiOS Artifacts for initialized agents..."
+# 6. Seed RAG context for downstream agents.
+echo "[ai-bootstrap] Seeding latest MiOS context for initialized agents..."
 if [[ -f "artifacts/repo-rag-snapshot.json.gz" ]]; then
-    # Shared scratchpad for cross-agent IPC
     mkdir -p .ai/foundation/shared-tmp/
     cp artifacts/repo-rag-snapshot.json.gz .ai/foundation/shared-tmp/latest-context.json.gz
-    # Sub-project local context
     cp artifacts/repo-rag-snapshot.json.gz agents/research/latest-context.json.gz
-    echo "✅ Context seeded to .ai/foundation/shared-tmp/ and agents/research/"
+    echo "[ai-bootstrap] Context seeded to .ai/foundation/shared-tmp/ and agents/research/"
 else
-    echo "⚠️ Warning: artifacts/repo-rag-snapshot.json.gz not found. Skip seeding."
+    echo "[ai-bootstrap] WARN: artifacts/repo-rag-snapshot.json.gz not found; skipping seed"
 fi