PHASE: align global phase numbering; relocate user-space content to mios-bootstrap

Document the global Phase-0..4 numbering (CLAUDE.md, INDEX.md,
ENGINEERING.md): the numbered automation/[0-9][0-9]-*.sh scripts are
sub-phases of Phase-2 (build), not top-level phases.

Relocate to mios-bootstrap.git (per system-prompt §3 — /etc/mios/, /home/,
/agents/ are bootstrap territory):
- etc/mios/ai/mi-os.yaml — moved to mios-bootstrap/etc/mios/ai/
- agents/research/ — knowledge graphs / RAG manifests live in bootstrap
- home/.keep — bootstrap stages user homes via profile/
- srv/.keep, srv/ai/.keep — directory structure declared by
  usr/lib/tmpfiles.d/mios.conf at runtime; placeholders unnecessary

.gitignore: drop the matching whitelist negations for /etc/mios/,
/home/, /srv/, /agents/. mios.git now only whitelists genuinely
system-layer paths.

install.sh: re-cast as the Phase-3 system-init half (sysusers, tmpfiles,
daemon-reload, service enable). Header documents that bootstrap
install.sh invokes this after Phase-1 overlay and Phase-2 package
install have completed.

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

Author: mios-dev

.gitignore

@@ -58,8 +58,6 @@
 !/tools/**
 !/config/
 !/config/**
-!/agents/
-!/agents/**
 
 # ─────────────────────────────────────────────────────────────────────────────
 # 4. /v1 — MiOS AI API surface
@@ -81,27 +79,15 @@ etc/containers/systemd/*
 !/etc/fapolicyd/
 etc/fapolicyd/*
 !/etc/fapolicyd/fapolicyd.rules
-!/etc/mios/
-!/etc/mios/**
 
-# ─────────────────────────────────────────────────────────────────────────────
-# 6. /home — placeholder only (no user data tracked)
-# ─────────────────────────────────────────────────────────────────────────────
-!/home/
-home/*
-!/home/.keep
-
-# ─────────────────────────────────────────────────────────────────────────────
-# 7. /srv — MiOS service data
-# ─────────────────────────────────────────────────────────────────────────────
-!/srv/
-srv/*
-!/srv/.keep
-!/srv/ai/
-!/srv/ai/**
+# /etc/mios/ is BOOTSTRAP territory (mios-bootstrap.git). Not tracked here.
+# /home/ is BOOTSTRAP territory. Per-user templates and skel live in mios-bootstrap.
+# /srv/ structure is created at runtime by usr/lib/tmpfiles.d/mios.conf — no
+# placeholder files tracked here.
+# /agents/ is BOOTSTRAP territory (knowledge graphs / RAG manifests).
 
 # ─────────────────────────────────────────────────────────────────────────────
-# 8. /root — MiOS shell skeleton for root user
+# 6. /root — MiOS shell skeleton for root user (system layer)
 # ─────────────────────────────────────────────────────────────────────────────
 !/root/
 root/*

CLAUDE.md

@@ -62,17 +62,31 @@ Day-2 (deployed host): `sudo bootc upgrade && sudo systemctl reboot`,
 
 ## Architecture (the parts that span multiple files)
 
-### The build pipeline
+### Global pipeline phases
+
+The full bootstrap → install pipeline is partitioned into five global phases.
+Every doc, log line, and orchestrator script in either repo refers to these
+by number:
+
+| Phase | Owner | Purpose |
+|---|---|---|
+| **Phase-0** | `mios-bootstrap.git/install.sh` | Preflight, profile load, host-kind detection, interactive identity capture. |
+| **Phase-1** | `mios-bootstrap.git/install.sh` (`trigger_mios_install`) | Total Root Merge — clone `mios.git` into `/`, copy bootstrap overlays (etc/, usr/, var/, profile/) on top. |
+| **Phase-2** | `Containerfile` + `automation/build.sh` (or FHS package install) | Build the running system. The numbered `automation/[0-9][0-9]-*.sh` scripts are *sub-phases* of Phase-2. |
+| **Phase-3** | `mios.git/install.sh` + `mios-bootstrap.git/install.sh` (`apply_user_profile`, `deploy_system_prompt`, `stage_user_profile_artifacts`) | systemd-sysusers, systemd-tmpfiles, daemon-reload, services; create the Linux user; stage `~/.config/mios/{profile.toml,system-prompt.md}` and host `/etc/mios/ai/system-prompt.md`. |
+| **Phase-4** | `mios-bootstrap.git/install.sh` (`reboot_prompt`) | Interactive `systemctl reboot`. |
+
+### The build pipeline (Phase-2 sub-phases)
 
 `Containerfile` is small. Its single big `RUN` calls
 `automation/08-system-files-overlay.sh` (overlay apply) then
 `automation/build.sh` — the master orchestrator that iterates every
-`automation/[0-9][0-9]-*.sh` in numeric order. Phase numbering is meaningful
-(repos → kernel → overlay → stack install → service config → user/GPU →
-AI/SELinux/polish → supply chain → finalize → from-source kmods → validate);
-do not renumber without understanding the dependency it encodes. Skipped
-under build: `08-system-files-overlay.sh` (runs pre-pipeline from
-Containerfile), `37-ollama-prep.sh` (CI-skipped).
+`automation/[0-9][0-9]-*.sh` in numeric order. The numbering is internal to
+Phase-2 and encodes dependencies (repos → kernel → overlay → stack install →
+service config → user/GPU → AI/SELinux/polish → supply chain → finalize →
+from-source kmods → validate). Do not renumber without understanding the
+dependency. Skipped under build: `08-system-files-overlay.sh` (runs
+pre-pipeline from Containerfile), `37-ollama-prep.sh` (CI-skipped).
 
 Every script sources `automation/lib/{common,packages,masking}.sh`. The
 masking library filters secrets out of build logs; output is teed through

ENGINEERING.md

@@ -1,13 +1,27 @@
 # MiOS Engineering Standards
 
-## Build pipeline
+## Global pipeline phases
+
+The end-to-end pipeline (bootstrap → install) is partitioned into five
+phases. The numbered `automation/[0-9][0-9]-*.sh` scripts are *sub-phases*
+of Phase-2 (build).
+
+| Phase | Owner | Description |
+|---|---|---|
+| Phase-0 | `mios-bootstrap.git/install.sh` | Preflight + profile load + identity capture |
+| Phase-1 | `mios-bootstrap.git/install.sh` | Total Root Merge of `mios.git` and `mios-bootstrap.git` to `/` |
+| Phase-2 | `Containerfile`/`automation/build.sh` | Build the running system (this section's subject) |
+| Phase-3 | `mios.git/install.sh` + bootstrap profile staging | systemd-sysusers/tmpfiles/daemon-reload + user create + per-user `~/.config/mios/{profile.toml,system-prompt.md}` |
+| Phase-4 | `mios-bootstrap.git/install.sh` | Reboot prompt |
+
+## Phase-2: build pipeline (sub-phases)
 
 `Containerfile` triggers `automation/build.sh`, which iterates every
 `automation/[0-9][0-9]-*.sh` in numeric order. Skipped under build:
 `08-system-files-overlay.sh` (runs pre-pipeline from `Containerfile`),
-`37-ollama-prep.sh` (CI-skipped). Phase numbering encodes dependency order
-and must be preserved when adding new scripts. See `CLAUDE.md` for the
-phase ranges.
+`37-ollama-prep.sh` (CI-skipped). Sub-phase numbering encodes dependency
+order and must be preserved when adding new scripts. See `CLAUDE.md` for
+the sub-phase ranges.
 
 Per-phase error handling: `automation/build.sh:234-237` toggles `set +e`
 around each script invocation so individual failures are captured in

INDEX.md

@@ -46,7 +46,24 @@ Spec: <https://platform.openai.com/docs/api-reference>.
 | `MIOS_USER` / `MIOS_HOSTNAME` | build | Default account/hostname baked into the image (`Containerfile:26-27`). |
 | `MIOS_FLATPAKS` | build | Comma-separated Flatpak refs (`Containerfile:28`). |
 
-## 5. Cross-references
+## 5. Global pipeline phases
+
+The end-to-end bootstrap → install pipeline is partitioned into five phases
+shared across both repos:
+
+| Phase | Owner repo | Purpose |
+|---|---|---|
+| Phase-0 | `mios-bootstrap` | Preflight, profile load, identity capture |
+| Phase-1 | `mios-bootstrap` | Total Root Merge (clone `mios.git` into `/`, overlay bootstrap) |
+| Phase-2 | `mios` | Build (Containerfile + `automation/[0-9][0-9]-*.sh` sub-phases, OR dnf install on FHS) |
+| Phase-3 | both | sysusers/tmpfiles/services + user create + per-user `~/.config/mios/{profile.toml,system-prompt.md}` staging |
+| Phase-4 | `mios-bootstrap` | Reboot |
+
+The user profile card at `etc/mios/profile.toml` (host) and
+`~/.config/mios/profile.toml` (per-user) is read in Phase-0 to seed defaults
+and re-written/staged in Phase-3.
+
+## 6. Cross-references
 
 - Build pipeline architecture: `CLAUDE.md`, `automation/build.sh`.
 - Filesystem and hardware layout: `ARCHITECTURE.md`.

agents/research/.keep

@@ -1,14 +1,17 @@
 #!/usr/bin/env bash
-# MiOS system-side installer (FHS overlay path).
+# MiOS system-side installer — runs as the system-init half of Phase-3
+# (Apply). Invoked by mios-bootstrap.git/install.sh after Phase-1 (overlay)
+# and Phase-2 (package install) have already completed.
 #
-# This script is invoked by the bootstrap installer on non-bootc Fedora hosts.
-# On bootc-managed hosts, do NOT run this -- use `bootc switch` instead.
+# Refuses to run on bootc-managed hosts (their /usr is read-only composefs);
+# on bootc, Phase-2/3 are handled by `bootc switch`.
 #
-# What it does:
-#   1. Refuses to run on bootc-managed hosts (their /usr is read-only composefs).
-#   2. Lays down the FHS overlay from this repository's working tree to /.
-#   3. Runs systemd-sysusers, systemd-tmpfiles, and reloads systemd units.
-#   4. Enables MiOS services.
+# What this script does (Phase-3 system-init responsibilities):
+#   1. Lay down any remaining FHS overlay rsyncs from this repository's
+#      working tree to / (idempotent if bootstrap already merged via git).
+#   2. systemd-sysusers (creates mios + sidecar service accounts).
+#   3. systemd-tmpfiles --create (declares /var/, /run/, /etc/cdi paths).
+#   4. systemctl daemon-reload + enable MiOS services.
 
 set -euo pipefail
 
@@ -25,7 +28,7 @@ if [[ $EUID -ne 0 ]]; then
 fi
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-echo "[INFO] MiOS system installer running from ${REPO_ROOT}"
+echo "[INFO] Phase-3 — MiOS system installer running from ${REPO_ROOT}"
 
 if [[ "${REPO_ROOT}" != "/" ]]; then
     # Apply FHS overlay. We rsync each top-level overlay dir if it exists.
@@ -59,5 +62,6 @@ if [[ -f /etc/containers/systemd/mios-ai.container ]]; then
     systemctl enable --now mios-ai.service || echo "[WARN] mios-ai.service not yet active; will retry on boot"
 fi
 
-echo "[ OK ] MiOS system installer complete."
-echo "       Log out and back in (or reboot) to pick up profile changes."
+echo "[ OK ] Phase-3 — MiOS system installer complete."
+echo "       Control returns to mios-bootstrap install.sh for Phase-3 user"
+echo "       staging and Phase-4 reboot prompt."