From b4788dd6b66278d7c3b9c4c4a17067ab4ff0c2fd Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Mon, 20 Apr 2026 21:13:47 -0400
Subject: [PATCH 01/15] sourceos: add artifact truth boundary note

---
 docs/ARTIFACT_TRUTH.md | 45 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 docs/ARTIFACT_TRUTH.md

diff --git a/docs/ARTIFACT_TRUTH.md b/docs/ARTIFACT_TRUTH.md
new file mode 100644
index 0000000..cd12468
--- /dev/null
+++ b/docs/ARTIFACT_TRUTH.md
@@ -0,0 +1,45 @@
+# SourceOS artifact truth
+
+`SourceOS` is the immutable substrate and artifact-truth repository for the Linux-side stack.
+
+This repo owns the definitions of **what** gets built and released, not the automation that stands builders up or the control plane that executes workflows.
+
+## This repo owns
+
+- flavor definitions
+- coreos-assembler / image-composition source material
+- Butane / Ignition source material
+- installer profile definitions
+- release channels
+- artifact manifests and release metadata
+
+## This repo does not own
+
+- Foreman/Katello management host automation
+- Tekton / Argo CD execution scaffolding
+- workspace controller logic
+- runner↔adapter protocol contracts
+- generic execution control plane behavior
+
+Those belong respectively in:
+- `SociOS-Linux/socios`
+- `SociOS-Linux/workstation-contracts`
+- `SocioProphet/sociosphere`
+- `SocioProphet/agentplane`
+- `SourceOS-Linux/sourceos-spec`
+
+## Directory intent
+
+- `flavors/` — named SourceOS flavor definitions
+- `cosa/` — coreos-assembler or build-source material
+- `butane/` — Butane source fragments and rendered-input source material
+- `installer/` — installer profile definitions for live ISO / PXE / recovery surfaces
+- `channels/` — release-channel declarations
+- `manifests/` — artifact manifests and release metadata
+
+## Follow-on
+
+Subsequent changes should:
+- replace stubs with canonical flavor and installer schemas aligned to `sourceos-spec`
+- bind artifact manifests to `ReleaseManifest` / `EvidenceBundle` families
+- add FCOS-specific build-source structure under `cosa/`

From ca9df408ef19047e665ecdf2b6a55170bc9f4b1a Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Mon, 20 Apr 2026 21:14:27 -0400
Subject: [PATCH 02/15] sourceos: add flavors scaffold

---
 flavors/README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 flavors/README.md

diff --git a/flavors/README.md b/flavors/README.md
new file mode 100644
index 0000000..41dca61
--- /dev/null
+++ b/flavors/README.md
@@ -0,0 +1,14 @@
+# SourceOS flavors
+
+This directory holds named SourceOS flavor definitions.
+
+A flavor is the stable substrate family that downstream automation composes into install media, disk images, or promoted release artifacts.
+
+## Intended contents
+
+- base flavor descriptors
+- flavor-specific package/image composition inputs
+- flavor policy notes
+- flavor-level metadata used by release channels
+
+See `sourceos-workstation.example.yaml` for the initial stub.

From b57532e9b18fd7a455a2a3aeb2ef4da9c3ca3a6a Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Mon, 20 Apr 2026 21:16:30 -0400
Subject: [PATCH 03/15] sourceos: add workstation flavor example

---
 flavors/sourceos-workstation.example.yaml | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 flavors/sourceos-workstation.example.yaml

diff --git a/flavors/sourceos-workstation.example.yaml b/flavors/sourceos-workstation.example.yaml
new file mode 100644
index 0000000..e4a1f86
--- /dev/null
+++ b/flavors/sourceos-workstation.example.yaml
@@ -0,0 +1,21 @@
+apiVersion: sourceos.ai/v0
+kind: Flavor
+metadata:
+  name: sourceos-workstation
+  labels:
+    family: workstation
+    substrate: fcos
+spec:
+  baseStream: stable
+  architecture:
+    - x86_64
+  buildMode: thin-personalization
+  releaseChannels:
+    - dev
+    - qa
+    - prod
+  installerProfiles:
+    - live-usb-default
+    - pxe-default
+  butaneRefs:
+    - butane/workstation/base.bu

From db407f26a58c1f0b8206ab7b6f52d4ae1ab68543 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Mon, 20 Apr 2026 21:17:03 -0400
Subject: [PATCH 04/15] sourceos: add cosa scaffold

---
 cosa/README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)
 create mode 100644 cosa/README.md

diff --git a/cosa/README.md b/cosa/README.md
new file mode 100644
index 0000000..e043ad2
--- /dev/null
+++ b/cosa/README.md
@@ -0,0 +1,10 @@
+# coreos-assembler / image composition source
+
+This directory is the landing zone for FCOS/SourceOS image composition source material.
+
+It should eventually contain:
+- config-git inputs for coreos-assembler
+- tree/manifests for thicker derivative lanes
+- release-build metadata and helper notes
+
+This directory is artifact truth only. Build orchestration belongs in `socios`.

From 993a87bf7b2348da3f41c06eecc376985df9a140 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 21 Apr 2026 21:43:24 -0400
Subject: [PATCH 05/15] sourceos: add butane scaffold

---
 butane/README.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 butane/README.md

diff --git a/butane/README.md b/butane/README.md
new file mode 100644
index 0000000..616f137
--- /dev/null
+++ b/butane/README.md
@@ -0,0 +1,5 @@
+# Butane source material
+
+This directory holds Butane source fragments and profile inputs that feed installer customization or first-boot provisioning.
+
+The intent is to keep SourceOS-specific, flavor-owned Butane source here while execution/rendering automation lives downstream.

From 94a53eb28fb7cdcc2491787fcf6cb8cdd9d82861 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 21 Apr 2026 22:51:19 -0400
Subject: [PATCH 06/15] sourceos: add base Butane stub

---
 butane/workstation/base.bu | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 butane/workstation/base.bu

diff --git a/butane/workstation/base.bu b/butane/workstation/base.bu
new file mode 100644
index 0000000..9b754ea
--- /dev/null
+++ b/butane/workstation/base.bu
@@ -0,0 +1,12 @@
+variant: fcos
+version: 1.6.0
+passwd:
+  users:
+    - name: sourceos
+      groups:
+        - wheel
+      ssh_authorized_keys: []
+storage:
+  files: []
+systemd:
+  units: []

From 23eff0509f3571e279f19b1920a9d13cd5cd0b65 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 00:10:43 -0400
Subject: [PATCH 07/15] sourceos: add installer scaffold

---
 installer/README.md | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 installer/README.md

diff --git a/installer/README.md b/installer/README.md
new file mode 100644
index 0000000..a3dcefa
--- /dev/null
+++ b/installer/README.md
@@ -0,0 +1,8 @@
+# Installer profiles
+
+This directory holds installer profile definitions for SourceOS artifact surfaces such as:
+- customized live USB / recovery media
+- PXE / UEFI HTTP boot install surfaces
+- other future install or recovery delivery modes
+
+Profiles here are artifact-truth inputs. Media customization and publishing automation live in `socios`.

From da486dabdcdbe1f7c3955767148b7afeb59fdd1f Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 00:11:19 -0400
Subject: [PATCH 08/15] sourceos: add live USB installer profile stub

---
 installer/live-usb-default.yaml | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 installer/live-usb-default.yaml

diff --git a/installer/live-usb-default.yaml b/installer/live-usb-default.yaml
new file mode 100644
index 0000000..5e36ad8
--- /dev/null
+++ b/installer/live-usb-default.yaml
@@ -0,0 +1,12 @@
+apiVersion: sourceos.ai/v0
+kind: InstallerProfile
+metadata:
+  name: live-usb-default
+  labels:
+    surface: live-usb
+spec:
+  baseArtifact: fcos-live-iso
+  ignitionMode: embed-live-and-dest
+  networkMode: optional-keyfiles
+  secureBoot: true
+  enrollmentProfileRef: urn:srcos:enrollment-profile:default-workstation

From 9f5943d5cc76f04f76f4377d6024f90e0bd9206d Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 00:12:41 -0400
Subject: [PATCH 09/15] sourceos: add PXE installer profile stub

---
 installer/pxe-default.yaml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 installer/pxe-default.yaml

diff --git a/installer/pxe-default.yaml b/installer/pxe-default.yaml
new file mode 100644
index 0000000..ea42d1d
--- /dev/null
+++ b/installer/pxe-default.yaml
@@ -0,0 +1,14 @@
+apiVersion: sourceos.ai/v0
+kind: InstallerProfile
+metadata:
+  name: pxe-default
+  labels:
+    surface: pxe
+spec:
+  baseArtifact: fcos-live-pxe
+  transport: uefi-http-boot
+  ignitionMode: dest-only
+  kernelArgs:
+    - ignition.firstboot
+    - ignition.platform.id=metal
+  enrollmentProfileRef: urn:srcos:enrollment-profile:default-workstation

From 6854d7decd81c87f97c2d46506b12bedddf7b381 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 00:14:11 -0400
Subject: [PATCH 10/15] sourceos: add channels scaffold

---
 channels/README.md | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 channels/README.md

diff --git a/channels/README.md b/channels/README.md
new file mode 100644
index 0000000..3898fd9
--- /dev/null
+++ b/channels/README.md
@@ -0,0 +1,11 @@
+# Release channels
+
+This directory holds SourceOS release-channel declarations.
+
+A channel defines the logical promotion lane for artifact families such as:
+- dev
+- qa
+- prod
+- customer or site-specific rings
+
+Channel policy and promotion automation are executed downstream; this repo owns the declared channel truth.

From ad8e36c9759b8a45088531c2a435260e7907dd20 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 00:15:03 -0400
Subject: [PATCH 11/15] sourceos: add dev channel stub

---
 channels/dev.yaml | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 channels/dev.yaml

diff --git a/channels/dev.yaml b/channels/dev.yaml
new file mode 100644
index 0000000..ed0d6d3
--- /dev/null
+++ b/channels/dev.yaml
@@ -0,0 +1,13 @@
+apiVersion: sourceos.ai/v0
+kind: ReleaseChannel
+metadata:
+  name: dev
+spec:
+  description: Development and integration ring for pre-production SourceOS artifacts.
+  promotionTargets:
+    - qa
+  allowedFlavors:
+    - sourceos-workstation
+  defaultInstallerProfiles:
+    - live-usb-default
+    - pxe-default

From 5f655bb54f52c063ec9a2ce4a911ec90807d6019 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 00:17:27 -0400
Subject: [PATCH 12/15] sourceos: add manifests scaffold

---
 manifests/README.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 manifests/README.md

diff --git a/manifests/README.md b/manifests/README.md
new file mode 100644
index 0000000..778fe12
--- /dev/null
+++ b/manifests/README.md
@@ -0,0 +1,7 @@
+# Artifact manifests
+
+This directory holds release and artifact metadata emitted or curated as part of SourceOS artifact truth.
+
+The long-term direction is to align these manifests with the shared `ReleaseManifest` and `EvidenceBundle` families in `sourceos-spec`.
+
+Automation that generates, signs, publishes, and promotes these manifests lives downstream in `socios` and related execution/control surfaces.

From f493a7f76064a010b3df31bea2a22e27d806677d Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 00:18:42 -0400
Subject: [PATCH 13/15] sourceos: add release manifest example

---
 manifests/release-manifest.example.json | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 manifests/release-manifest.example.json

diff --git a/manifests/release-manifest.example.json b/manifests/release-manifest.example.json
new file mode 100644
index 0000000..644a843
--- /dev/null
+++ b/manifests/release-manifest.example.json
@@ -0,0 +1,22 @@
+{
+  "id": "urn:srcos:release:sourceos-workstation-dev-0001",
+  "type": "ReleaseManifest",
+  "specVersion": "2.0.0",
+  "sourceBuildRequestRef": "urn:srcos:build-request:sourceos-workstation-dev-0001",
+  "artifactRefs": [
+    "artifacts/sourceos-workstation-dev.iso"
+  ],
+  "artifactHashes": [
+    "sha256:REPLACE_WITH_REAL_DIGEST"
+  ],
+  "sbomRefs": [],
+  "evidenceRefs": [],
+  "labels": {
+    "flavor": "sourceos-workstation",
+    "channel": "dev",
+    "surface": "live-usb"
+  },
+  "channel": "dev",
+  "status": "draft",
+  "createdAt": "1970-01-01T00:00:00Z"
+}

From d58de45d7e56421382e652fd442fab8259779ea7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 23 Apr 2026 22:13:25 +0000
Subject: [PATCH 14/15] fix: resolve markdownlint MD032 and yamllint
 document-start issues

Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>
---
 channels/README.md                        | 1 +
 channels/dev.yaml                         | 2 +-
 cosa/README.md                            | 1 +
 docs/ARTIFACT_TRUTH.md                    | 2 ++
 docs/RELEASES.md                          | 1 +
 flavors/sourceos-workstation.example.yaml | 2 +-
 installer/README.md                       | 1 +
 installer/live-usb-default.yaml           | 2 +-
 installer/pxe-default.yaml                | 2 +-
 9 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/channels/README.md b/channels/README.md
index 3898fd9..c9a58c4 100644
--- a/channels/README.md
+++ b/channels/README.md
@@ -3,6 +3,7 @@
 This directory holds SourceOS release-channel declarations.
 
 A channel defines the logical promotion lane for artifact families such as:
+
 - dev
 - qa
 - prod
diff --git a/channels/dev.yaml b/channels/dev.yaml
index ed0d6d3..55ef976 100644
--- a/channels/dev.yaml
+++ b/channels/dev.yaml
@@ -1,5 +1,5 @@
+---
 apiVersion: sourceos.ai/v0
-kind: ReleaseChannel
 metadata:
   name: dev
 spec:
diff --git a/cosa/README.md b/cosa/README.md
index e043ad2..542d620 100644
--- a/cosa/README.md
+++ b/cosa/README.md
@@ -3,6 +3,7 @@
 This directory is the landing zone for FCOS/SourceOS image composition source material.
 
 It should eventually contain:
+
 - config-git inputs for coreos-assembler
 - tree/manifests for thicker derivative lanes
 - release-build metadata and helper notes
diff --git a/docs/ARTIFACT_TRUTH.md b/docs/ARTIFACT_TRUTH.md
index cd12468..75ce973 100644
--- a/docs/ARTIFACT_TRUTH.md
+++ b/docs/ARTIFACT_TRUTH.md
@@ -22,6 +22,7 @@ This repo owns the definitions of **what** gets built and released, not the auto
 - generic execution control plane behavior
 
 Those belong respectively in:
+
 - `SociOS-Linux/socios`
 - `SociOS-Linux/workstation-contracts`
 - `SocioProphet/sociosphere`
@@ -40,6 +41,7 @@ Those belong respectively in:
 ## Follow-on
 
 Subsequent changes should:
+
 - replace stubs with canonical flavor and installer schemas aligned to `sourceos-spec`
 - bind artifact manifests to `ReleaseManifest` / `EvidenceBundle` families
 - add FCOS-specific build-source structure under `cosa/`
diff --git a/docs/RELEASES.md b/docs/RELEASES.md
index 49de3e1..a81fc68 100644
--- a/docs/RELEASES.md
+++ b/docs/RELEASES.md
@@ -48,6 +48,7 @@ We consider **Truth Plane v0.1** achieved when:
 - A compatibility alias remains for at least one minor cycle.
 
 Example:
+
 - `_nft_set_elements_json_from_obj` is a compatibility alias for `parse_nft_set_elements_json` and will be removed after v0.1.
 
 ---
diff --git a/flavors/sourceos-workstation.example.yaml b/flavors/sourceos-workstation.example.yaml
index e4a1f86..e9e5556 100644
--- a/flavors/sourceos-workstation.example.yaml
+++ b/flavors/sourceos-workstation.example.yaml
@@ -1,5 +1,5 @@
+---
 apiVersion: sourceos.ai/v0
-kind: Flavor
 metadata:
   name: sourceos-workstation
   labels:
diff --git a/installer/README.md b/installer/README.md
index a3dcefa..0a89a21 100644
--- a/installer/README.md
+++ b/installer/README.md
@@ -1,6 +1,7 @@
 # Installer profiles
 
 This directory holds installer profile definitions for SourceOS artifact surfaces such as:
+
 - customized live USB / recovery media
 - PXE / UEFI HTTP boot install surfaces
 - other future install or recovery delivery modes
diff --git a/installer/live-usb-default.yaml b/installer/live-usb-default.yaml
index 5e36ad8..2d44a2d 100644
--- a/installer/live-usb-default.yaml
+++ b/installer/live-usb-default.yaml
@@ -1,5 +1,5 @@
+---
 apiVersion: sourceos.ai/v0
-kind: InstallerProfile
 metadata:
   name: live-usb-default
   labels:
diff --git a/installer/pxe-default.yaml b/installer/pxe-default.yaml
index ea42d1d..f227f4a 100644
--- a/installer/pxe-default.yaml
+++ b/installer/pxe-default.yaml
@@ -1,5 +1,5 @@
+---
 apiVersion: sourceos.ai/v0
-kind: InstallerProfile
 metadata:
   name: pxe-default
   labels:

From 3807f6fbdf728274dff42868db6090a1eb4e460c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 23 Apr 2026 22:14:55 +0000
Subject: [PATCH 15/15] fix: restore kind fields accidentally dropped during
 document-start fix

Agent-Logs-Url: https://github.com/SociOS-Linux/SourceOS/sessions/7e551304-1d9a-40e5-b9fc-7d8714b6787b

Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>
---
 channels/dev.yaml                         | 1 +
 flavors/sourceos-workstation.example.yaml | 1 +
 installer/live-usb-default.yaml           | 1 +
 installer/pxe-default.yaml                | 1 +
 4 files changed, 4 insertions(+)

diff --git a/channels/dev.yaml b/channels/dev.yaml
index 55ef976..8c30ec0 100644
--- a/channels/dev.yaml
+++ b/channels/dev.yaml
@@ -1,5 +1,6 @@
 ---
 apiVersion: sourceos.ai/v0
+kind: ReleaseChannel
 metadata:
   name: dev
 spec:
diff --git a/flavors/sourceos-workstation.example.yaml b/flavors/sourceos-workstation.example.yaml
index e9e5556..6756df7 100644
--- a/flavors/sourceos-workstation.example.yaml
+++ b/flavors/sourceos-workstation.example.yaml
@@ -1,5 +1,6 @@
 ---
 apiVersion: sourceos.ai/v0
+kind: Flavor
 metadata:
   name: sourceos-workstation
   labels:
diff --git a/installer/live-usb-default.yaml b/installer/live-usb-default.yaml
index 2d44a2d..5e928d7 100644
--- a/installer/live-usb-default.yaml
+++ b/installer/live-usb-default.yaml
@@ -1,5 +1,6 @@
 ---
 apiVersion: sourceos.ai/v0
+kind: InstallerProfile
 metadata:
   name: live-usb-default
   labels:
diff --git a/installer/pxe-default.yaml b/installer/pxe-default.yaml
index f227f4a..d68bb33 100644
--- a/installer/pxe-default.yaml
+++ b/installer/pxe-default.yaml
@@ -1,5 +1,6 @@
 ---
 apiVersion: sourceos.ai/v0
+kind: InstallerProfile
 metadata:
   name: pxe-default
   labels: