docs: STRATEGY.md — hybrid kickstart bootstrap + bootc OCI on secureblue

Locks in the strategic decision from 2026-05-05 secureblue research
agent: pivot the technical base toward bootc/OCI, but as a layer over
secureblue's `securecore-kinoite-hardened-userns` rather than a
Containerfile-from-scratch.

## What changed

- New: `docs/STRATEGY.md` — full hybrid plan (kickstart bootstrap →
  first-boot bootc rebase → bootc-only at v1.0). Documents secureblue
  rationale, our overrides (drop Trivalent, restore sudo + Xwayland),
  next concrete steps for v0.7 spike (BlueBuild recipe + GH Actions
  workflow + `veilor-firstboot-rebase` one-shot).

- Updated: `docs/ROADMAP.md` v0.7 bootc-spike subsection — supersedes
  the Agent 3 Containerfile-from-scratch plan with the BlueBuild
  layering plan. Spike compresses 1 week → 2 days; hardening review
  inherited from 30 secureblue contributors.

## Why hybrid, not pure pivot

- Anaconda's LUKS UX (single passphrase prompt + custom
  partitioning) is mature; bootc-image-builder's installer is not yet
  on par. Keep the kickstart as the bootstrap.
- bootc upgrade gets us atomic A/B + signed image chain + instant
  rollback that we can't realistically build alone with our
  contributor count.
- The kickstart work is not lost — it becomes the day-zero installer
  through v0.7. v1.0 deprecates it entirely once bootc-image-builder
  installer ISO matures.

## Why secureblue, not Athena (Arch)

| Axis | secureblue | Athena OS |
|---|---|---|
| Maintainers | 30 | 8 |
| MAC enforcing OOB | SELinux + custom policy | AppArmor active, profiles mostly unconfined |
| Atomic / immutable updates | Yes (bootc/rpm-ostree) | No (rolling) |
| Threat model published | No | Yes |
| MS-signed Secure Boot shim | Yes (Fedora shim) | Yes (with auto-MOK) |

Athena's only structural advantage is the published threat model.
We're already drafting one (Agent 5 of 2026-05-05 wave) — we get
that win regardless. secureblue's contributor count + atomic update
infrastructure is the leverage.

## Strategic credibility win

Publishing `docs/THREAT-MODEL.md` BEFORE the v0.7 launch positions
veilor-os ahead of secureblue (no threat model) and Athena (has
threat model but smaller contributor base) on the one axis that
matters most.

## Open questions documented in STRATEGY.md

- secureblue contribution acceptance for upstream patches (USBGuard
  id-based-rules fix, threat model framework)
- Brave vs Mullvad-Browser pick for default browser
- bootc rebase first-boot fallback if rebase fails
- Fedora 44 transition timing follows secureblue's release tags

docs/ROADMAP.md

@@ -223,17 +223,44 @@ public, benchmarks come after.
    After threat model, not before.
 5. **Press kit** — wallpapers, logo, screenshots, feature one-liner.
 
-### bootc-image-builder spike (PROMOTED from v1.0+)
+### Hybrid bootc spike — layer on secureblue (REVISED 2026-05-05)
 
-The v0.5.27–31 grind cost us hours on anaconda + RPM-6.0 +
+The original v0.7 entry called for a Containerfile-from-scratch
-`--cmdline` mode brittleness: three install failures, kernel-cmdline
+spike on `quay.io/fedora/fedora-bootc:43`. Research on 2026-05-05
-written to four different places before one worked, transaction-progress
+(see `docs/STRATEGY.md` and
-patches that masked real bugs. **bootc-image-builder builds a
+`docs/research/2026-05-05-agent-wave/`) found a faster path:
-`Containerfile` once and gets a bootable image** — no anaconda, no
+**layer veilor's branding + threat model + UX on top of
-kickstart, no `%post --nochroot` vs `%post`, no
+secureblue's already-shipping `securecore-kinoite-hardened-userns`
-`CollectKernelArgumentsTask`. A v0.7 spike (NOT v1.0) evaluates whether
+OCI image** via a BlueBuild recipe.
-the next major rev should rebase on it. Spike outcome determines
+
-whether `veilor-atomic` (stretch goal) becomes the mainline.
+Reasoning:
+
+- secureblue has 30 active contributors, 940 stars, 56 commits
+  in the last 5 weeks. They've already implemented the hardening
+  surface we'd need to build alone (sysctl + kargs + SELinux
+  custom policy + USBGuard + hardened-malloc + Unbound DoT +
+  cosign-signed OCI build pipeline).
+- Containerfile-from-scratch spike: 1 week to first ISO.
+  BlueBuild recipe extending secureblue: ~2 days, ~200 lines
+  YAML. The hardening review is inherited.
+- secureblue does NOT publish a threat model. Athena OS does
+  (their main differentiator, only public threat model in
+  hardened-Linux 2026). Our `docs/THREAT-MODEL.md` (drafted) gets
+  us ahead of both on the one axis that matters most for a
+  security-branded distro.
+
+Hybrid path locked: kickstart ISO stays as the **bootstrap
+installer** (Anaconda's LUKS UX is mature). On first boot, a
+one-shot `veilor-firstboot-rebase` service runs `bootc rebase
+ghcr.io/veilor/veilor-os:43`. From then on, `bootc upgrade` is
+the update channel. v1.0 deprecates the kickstart entirely.
+
+Overrides we apply over secureblue: replace Trivalent (their
+single-maintainer browser fork) with Brave or Mullvad-Browser;
+keep sudo (revert `run0`-only); re-enable Xwayland.
+
+Full plan: `docs/STRATEGY.md`. Spike will land in
+`bluebuild/recipe.yml` plus `.github/workflows/build-bluebuild.yml`.
 
 ---
 

docs/STRATEGY.md

@@ -0,0 +1,137 @@
+# veilor-os Strategy — Hybrid kickstart bootstrap + bootc OCI
+
+Decision date: **2026-05-05**
+Locked at: **v0.5.31 → v0.7 spike → v1.0**
+
+## TL;DR
+
+- Keep the Anaconda-driven kickstart ISO as the **bootstrap installer**
+  (LUKS UX is mature, single passphrase prompt, custom partitioning
+  works).
+- On first boot, the installed system is automatically rebased to a
+  **veilor-os OCI image** built via BlueBuild on top of secureblue's
+  `securecore-kinoite-hardened-userns`.
+- All future updates flow through `bootc upgrade` — atomic A/B,
+  instant rollback, cosign-signed.
+- The kickstart-driven mutable-root path is deprecated at v1.0; kept
+  alive as fallback through v0.7.
+
+## Why hybrid, not pure pivot
+
+Pure pivot to bootc-from-scratch (Agent 3's spike plan) was **1 week
+to first ISO**. Pure pivot to layering on secureblue is **2 days to
+first ISO** because the hardening work is already done. But both
+require throwing away the partitioning UX we already have working in
+Anaconda.
+
+Hybrid:
+- **Day-zero install:** Anaconda kickstart + custom partitioning +
+  LUKS prompt (what we have today). User experience = unchanged.
+- **First boot, post-LUKS-unlock:** `bootc rebase
+  ghcr.io/veilor/veilor-os:43` runs once; pulls the OCI image; next
+  reboot lands in the veilor OCI tree.
+- **Day-2:** `bootc upgrade` cadence for everything from then on.
+
+We keep what works, pivot the part that doesn't.
+
+## Why secureblue underneath
+
+| Question | Answer |
+|---|---|
+| Maintainers | secureblue: 30 contributors, 56 commits/5wks. veilor-os: solo. |
+| Hardening surface | secureblue ships sysctl + kargs + SELinux + USBGuard + hardened-malloc + DoT — far more than we'd build alone. |
+| Build pipeline | BlueBuild → cosign-signed OCI in GH Actions (`build-all.yml`, `trivy.yml`). |
+| Update model | bootc upgrade with A/B + instant rollback + signed image chain. |
+| Variants | `kinoite-hardened-userns` is the KDE+Wayland+SELinux variant we'd want. |
+| License | Apache-2.0 (compatible with our MIT). |
+
+What we override in our recipe:
+
+- **Browser**: Trivalent (their fork) → Brave / Mullvad-Browser.
+  Single-maintainer browser fork is unacceptable risk for daily-driver
+  audience.
+- **`run0` instead of sudo**: revert. Breaks too many workflows.
+- **Xwayland disabled**: revert. Some apps still need it.
+- **veilor branding**: theme, KDE color scheme, Plymouth, SDDM, font,
+  os-release. All `overlay/*` ports verbatim from current repo.
+
+## Strategic credibility win
+
+secureblue does NOT publish a threat model. Athena OS does, and it's
+their main differentiator. We've already drafted
+`docs/THREAT-MODEL.md` (Agent 5 of 2026-05-05 wave). Publishing that
+*before* the v0.7 launch positions veilor-os ahead of secureblue and
+Athena on the one axis that matters most for a security-branded
+distro: **honest, scoped, public threat model**.
+
+## Roadmap implications
+
+| Version | Status | Path |
+|---|---|---|
+| v0.5.31 | shipped | Anaconda kickstart, mutable root |
+| v0.5.32 | active — top blockers from 9-agent wave | Anaconda kickstart |
+| v0.5.x → v0.6 | maintenance | Anaconda kickstart, ergonomics + UX polish |
+| **v0.7 spike** | **2-day BlueBuild prototype** | First veilor OCI image extending secureblue-kinoite-hardened |
+| v0.7 ship | ISO bootstraps install, first boot rebases to OCI | Hybrid path live |
+| **v1.0** | **bootc-only**, kickstart deprecated | `bootc upgrade` for all updates |
+
+The `bootc-image-builder` spike plan (Agent 3) is **superseded** by
+this hybrid: don't build a Containerfile from scratch on
+`fedora-bootc:43`. Instead, write a BlueBuild recipe on
+`securecore-kinoite-hardened-userns`. Spike compresses 1 week → 2 days.
+
+## Next concrete steps
+
+### v0.5.32 — current (no strategy change)
+
+Ship the 7 blockers from `docs/research/2026-05-05-agent-wave/`:
+suspend/resume wifi fix, firstboot WantedBy, USBGuard id-rules,
+firewalld tailscale0 zone, KMS modeset, /etc/skel branding, virtio-9p
+log capture.
+
+### v0.7-spike (2 days)
+
+1. New repo dir: `bluebuild/recipe.yml`.
+2. `from`: `ghcr.io/secureblue/securecore-kinoite-hardened-userns:latest`.
+3. Override modules:
+   - `type: files` — stamp our `overlay/*` tree (branding, themes,
+     veilor scripts, sddm theme, plymouth theme).
+   - `type: rpm-ostree` — install Brave + restore Xwayland.
+   - `type: rpm-ostree` — remove Trivalent.
+   - `type: brand` — PRETTY_NAME, GRUB_DISTRIBUTOR, distributor URL.
+4. `.github/workflows/build-bluebuild.yml` — pull BlueBuild action,
+   build + cosign sign + push to GHCR.
+5. `kickstart/install.ks` — add a one-shot `veilor-firstboot-rebase`
+   service that runs `rpm-ostree rebase ghcr.io/veilor/veilor-os:43`
+   then disables itself. User reboots once and is on the OCI image.
+
+### v1.0 — bootc-only
+
+- Drop `kickstart/veilor-os.ks`, drop `livecd-creator` workflow.
+- Keep `installer-iso.toml` for the bootstrap ISO (built via
+  bootc-image-builder); the OCI image is the source of truth.
+- `veilor-update` becomes thin `bootc upgrade --apply` wrapper.
+
+## Open questions
+
+- Does secureblue accept upstream contributions? If yes, send our
+  USBGuard id-based-rules fix and our threat model framework.
+- Brave vs Mullvad-Browser: Brave has telemetry concerns out of box;
+  Mullvad-Browser is Tor-Browser-derived but not designed for
+  daily-driver. Test both in spike.
+- Recovery flow when bootc rebase fails on first boot — need fallback
+  to keep the kickstart-installed system bootable. Likely already
+  handled by bootc's A/B; verify in spike.
+- Fedora 44 transition: secureblue tracks Fedora releases (current
+  `v4.9` on F44). If we follow, we get F44 for free at the same time
+  upstream does.
+
+## See also
+
+- `docs/THREAT-MODEL.md` — drafted, needs publish for v0.7
+- `docs/ROADMAP.md` — to be updated to reflect this strategy
+- `docs/research/2026-05-05-agent-wave/03-bootc-spike-plan.md` —
+  superseded by this hybrid (kept as reference for the
+  Containerfile-from-scratch alternative)
+- secureblue: <https://github.com/secureblue/secureblue>
+- BlueBuild: <https://blue-build.org>