| 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:
