oem-hardware-hooks

name	oem-hardware-hooks
version	1.1
last_updated	2026-08-08
id	oem-hardware-hooks
one_line_purpose	Add OEM hardware first-boot setup hooks safely.
entry_point	docs/skills/oem-hardware-hooks/SKILL.md
category	test-authoring
mcp_compliance_level	partial
optimization_status	draft
status	active
dependencies	[]
tags	["hardware","oem","first-boot","hooks","shellcheck"]
description	OEM hardware first-boot setup hooks in projectbluefin/common. Use when adding hardware-specific setup, understanding hook directories and versioning contract, or applying shellcheck requirements.
metadata	{"type":"reference"}

oem-hardware-hooks — OEM Hardware First-Boot Setup in common

How to add, move, or maintain hardware-specific first-boot setup hooks in projectbluefin/common. Covers the hook directories, the versioning contract, shellcheck requirements, and what belongs here vs upstream.

---

When to Use

• Adding new hardware-specific first-boot behavior to projectbluefin/common
• Migrating a hook from a downstream repo (bluefin, bluefin-lts) into common
• Debugging a hook that burned its stamp prematurely or never ran
• Adding a new OEM vendor to the data-driven 20-oem-brew.sh hook

When NOT to Use

• Adding Fedora/Bluefin-version-specific logic that should stay downstream
• Installing packages that depend on services only one variant ships
• Anything requiring brew install --cask without trust (use Brewfile)

---

Hook directories

Two directories are scanned automatically at first boot — no registration needed:

Rule of thumb for where to place desktop or session settings

• Image default for all users → system_files/bluefin/usr/share/glib-2.0/schemas/zz0-bluefin-modifications.gschema.override
• Locked (users cannot override) → update both the override and system_files/bluefin/etc/dconf/db/distro.d/locks/01-bluefin-locked-settings
• One-time first-boot action for current user → system_files/shared/usr/share/ublue-os/user-setup.hooks.d/ with version-script contract
• Do not create a new GNOME schema override file for a single setting when the existing Bluefin override already exists.

Directory	Runner	Runs as
system_files/shared/usr/share/ublue-os/system-setup.hooks.d/	ublue-system-setup (systemd system service)	root
system_files/shared/usr/share/ublue-os/user-setup.hooks.d/	ublue-user-setup (systemd user service)	current user

Name scripts with a numeric prefix (10-, 20-) to control execution order.

---

The version-script contract

Every hook must begin with: